STEM Releng

From Eclipsepedia

Jump to: navigation, search

Contents

STEM Release Engineering

This page details how to operate the STEM builder to create binary, platform-specific builds of STEM. This information is for advanced users and committers only.

Background

The STEM build process is built on several foundational pieces of the Eclipse Platform. These pieces include:

  • Eclipse Products
  • Eclipse Features
  • PDE Build Process
  • P2 Provisioning

These fundamental aspects of the Eclipse Platform are orchestrated to build platform-specific binaries of STEM.

Adding New Code to the Builder

This section describes how to add new plug-ins, features, and third-party dependencies to the STEM Build process.

Adding a new plug-in to an existing feature

STEM is built from Eclipse plug-ins. This section describes how to add one or more new plug-ins to the STEM build process to an existing feature. If you want to create a new feature, see the next section.

  • Determine which Feature(s) the plug-in(s) should be added to
    See note above about feature cross-dependencies to help determine which features you should add the plug-in to
    1. In Eclipse, expand the feature project the plug-in(s) should be added to and double-click feature.xml
    2. In the Feature Editor, select the Plug-ins tab
    3. On the Plug-ins and Fragments page, click the Add... button
    4. In the Plug-in Selection dialog, type the name of the plug-in you wish to add. When it shows up in the list, select it and click OK
      Repeat this step for all plug-ins you wish to add to this feature
    5. Save feature.xml (File-Save or Control-S)
    6. Commit feature.xml (Right-click Team-Commit)
  • Add the plug-in to SVN
    1. In Eclipse, select the plug-in project you wish to add.
    2. Right click on the project, highlight Team and select Share Project
    3. Follow the steps to add it to the repository.
      Note: The STEM Source Repository has a specific layout. Please make sure to place your new plug-in in an appropriate location. Plug-ins are grouped in folders with other plug-ins of similar functionality (such as disease models ). Remember this location, as it's needed for the build.map step below.
  • Add the plug-in to the build map
    1. In Eclipse, expand the org.eclipse.stem.releng project
    2. Expand the maps folder and open stem.map in the text editor
    3. Add the plug-in to the build map. The syntax is as follows:
      plugin@[PLUGIN_NAME]=COPY,${checkoutDir}/[REPOSITORY_PATH],[PLUGIN_NAME]
      Where:
      [PLUGIN_NAME] should be replaced with the plug-in name (Example: org.eclipse.stem.core)
      [REPOSITORY_PATH] should be replaced with the path in SVN where the plug-in was added, relative to trunk (Example: plug-ins added to /trunk/core would use core for the [REPOSITORY_PATH])
      Important Note: Plug-ins are grouped in the build map for project set generation. To ensure that a plug-in gets checked out, make sure it's grouped appropriately with similar plug-ins
    4. Save and commit build.map

Adding a new feature

If the new functionality you're adding is substantially different from existing functionality in STEM (such as a new type of modeling, like climate modeling ), then it may be appropriate to add it as a new feature. These steps will help you add a new Eclipse Feature to STEM's runtime and build process.

Important Note: These steps add a feature to the default build process (which, in turn, adds the feature to the main STEM distribution). If you do not wish for the feature to be part of the STEM distribution, only follow the first step below (Creating the Feature Project).

  • Create the Feature Project
    1. In Eclipse, select the File menu and click New
    2. In the New wizard, expand the Plug-in Development category and select Feature Project . Click Next
    3. On the New Feature page, populate the fields
      • Project Name should be fully qualified and end with .feature (Example: org.eclipse.stem.new.feature)
      • Feature ID should be the same as Project Name
      • Feature Name should be a short description of what functionality the feature provides
      • Feature Provider should be your organization's name (Example: Eclipse Foundation)
    4. Click Next
    5. On the Referenced Plug-ins and Fragments page, select the plug-ins to be part of this feature.
      Note: If the plug-ins aren't created yet, use the steps from the previous section to add them to the feature later
    6. Click Finish
    7. Add the new feature project to SVN
      Note: In the STEM Source repository, feature projects are placed in the /trunk/features folder.
  • Add the Feature to the STEM Product Feature (optional)
    1. In Eclipse, expand the org.eclipse.stem.product.feature project. Open feature.xml
    2. In the Feature Editor , select the Included Features tab
    3. On the Included Features page, click Add
    4. In the Feature Selection dialog, type in your Feature Project's name. When found, select it and click OK
    5. Save and commit feature.xml
  • Add the Feature to the build map
    1. In Eclipse, expand the org.eclipse.stem.releng project
    2. Expand the maps folder and open stem.map in the text editor
    3. Add the feature to the build map at the end of the rest of the features. The syntax is as follows:
      feature@[FEATURE_NAME]=COPY,${checkoutDir}/features,[FEATURE_NAME]
      Where:
      [FEATURE_NAME] should be replaced with the feature project name (Example: org.eclipse.stem.core.feature)
    4. Save and commit build.map

Adding a new third-party dependency

Instructions will be added later

Running the STEM Builder

The section describes how to setup and run the Eclipse PDE Builder to create a STEM binary.

Setting up your environment

Requirements

  • Environment with a compatible shell (bash)
    • Windows users are recommended to run the builder from cygwin or a similar interpreter
  • Subversion command-line client (svn)
  • Java J2SE Development Kit (JDK) 6.0 (Oracle or IBM)
  • Eclipse Classic SDK with the following features installed:
    • Eclipse Modeling Framework (EMF)
    • Eclipse Business Intelligence and Reporting Tools (BIRT) Framework
    • Eclipse Zest Framework
    • Eclipse RCP Delta Pack (for Eclipse 3.7.0, see here)
    • Eclipse Releng Tools (For Eclipse 3.7.0, see here)

Checking out the source from SVN

The STEM Builder looks for projects based on the SVN Repository layout, not in the flat structure of an Eclipse workspace. Therefore, you should checkout the repository AS IS using the SVN command line client.

This svn command checks out the STEM source from the SVN trunk into the current working directory.

svn co http://dev.eclipse.org/svnroot/technology/org.eclipse.stem/trunk .

To checkout from a different branch, replace trunk with branches and include the branch name. Example that checks out the STEM_1_2_1 branch:

svn co http://dev.eclipse.org/svnroot/technology/org.eclipse.stem/branches/STEM_1_2_1 .

One advantage of checking out this way is you can quickly update the entire code base using:

svn update

Running the STEM Builder

The STEM builder is built on top of the Eclipse PDE build process. For STEM, it's three steps that are controlled by environment variables:

  1. Build the STEM Features
  2. Create and Package the STEM Product
  3. Run JUnit Tests

Each step can be enabled or disabled using appropriate environment switches

Environment Variables

The following are the environment variables that should be defined before invoking the STEM build script.

Important Note: The org.eclipse.stem.releng/bootstrapManual.sh script defines these environment variables.

Variable Name Required Example Description
SKIPFEATURE yes false Skip creating the STEM Features. In most cases, this should be false
SKIPPRODUCT yes false Skip creating and packaging the STEM Product. In most cases, this should be false
RUNTESTS yes true Run the JUnit tests after the features and product are created.
JAVA_HOME yes /usr/local/java Path to the root folder of your JDK. The java executable should be located at /bin/java relative to this path
ECLIPSE_HOME yes /usr/local/eclipse Path to the root folder of your Eclipse SDK installation. The eclipse plugins folder should be located at /plugins relative to this path

Running the JUnit Tests

Continuous Integration (CI) Automated Builds