6.1 prepare

Introduction

When a new release of the RTC SDK is made available on the download page (for old versions, please refer to the old rtc downloads section), new configuration files (in tool/sdk_files) and database files (in tool/db_presets) have to be created. This is necessary for enabling the creation of run times that use newer versions of the SDK. This page is a detailed explanation of the steps necessary for creating these files, and how to make them available to other users.

Preparation

1. Make sure that you have a jazz development environment with at least the bootstrap task already executed.
2. Download JTS-CCM-Keys and RTC-SDK-Server zip files with matching versions, of the version that you want to create a new release for. Place these in the jde/servers and jde/sdks folders accordingly. This requires an IBM login and can also be accomplished using the download task.
3. Download the Feature Based Launches eclipse dropin from the IBM wiki or using this direct link. This requires an IBM login and can also be accomplished using the download task.
4. Extract the content of the launcher442.zip into the jde/dev/dropins folder. Make sure to only copy the jar file from inside the zip archive: /launcher442/plugins/com.ibm.team.dev.launch_0.3.13.201605301342.jar
5. Run the ./gradlew ideClean task to make sure no previously initialized eclipse environments still exist.

Double Check

This and the following examples will create files for the 6.0.6.1 release, but other versions will work in the same way.

1. Run the Info task and check that both SDK and Server versions are available for the new release.

$ ./gradlew info

> Task :info
Available SDK versions:
        RTC-SDK-Server-6.0.6.1.zip
Available Servers / JRE versions:
        JTS-CCM-keys-Linux64_6.0.6.1.zip

Note that there are no available databases and configurations for this release. This makes it clear that it is necessary to follow these instructions for creating a new release. Make sure that you are using the newest version of the jazz development environment from GitHub before proceeding.

2. Attempt to run a setup task for the new version. This should fail, as the files do not exist yet.

$ ./gradlew setup --sdk=6.0.6.1

> Task :setup
SDK Version 6.0.6.1 selected for runtime setup
Missing file for version 6.0.6.1 in directory jde/dbs

3. Make sure that the dropin jar file has been copied correctly. The folder structure of the jde/dev folder should look like this:

jde/dev
├── dropins
│   └── com.ibm.team.dev.launch_0.3.13.201605301342.jar
├── projects
│   ├── configs
│   │   └── teamserver.properties
│   ├── launches
│   │   ├── Create Development Environment Database.launch
│   │   └── Launch Development Environment.launch
│   └── tests
│       └── build.properties
└── release
    ├── config
    └── db

and the Info task should list the dropin accordingly:

 ➜  ./gradlew info

Available drop-ins:
        com.ibm.team.dev.launch_0.3.13.201605301342.jar

Creating a new release

Creating a new release requires the usage of the following tasks in the correct order. This process has been streamlined so that minimal user interaction is necessary, however, the process is still fairly intricate. Make sure to properly follow these instructions so that a working environment can be created using the files that are generated.

Initialize Task

This task will create an Eclipse Plugin Environment, preconfigured to use the newest available sdk as the target platform. Depending on your machine and operating system, the initialize task will take a considerable amount of time to finish. It is not unsual for directory and file exceptions to occur, but generally, these can be ignored. Once the task has completed, continue with the next task.

IDE Task

The ide task will run the previously initialized eclipse environment. After a configuration phase, a jazz-community branded eclipse should start.

This is where most issues will occur with the rather fickle process of creating a new sdk configuration. If everything went well, you should see a Project Explorer with 2 Projects. If you don't see the Development Environment Launches, run the ./gradlew launches task to redeploy them. Sadly, the configuration of the target platform can fail, resulting in no projects being shown. Should this be the case, you will have to manually set up the target platform. If you can see the projects as in the following screenshot, continue with Running the necessary Launches, otherwise try Setting up the target platform first.

Running the necessary Launches

Once you can see the Development Environment Launches project in the Project Explorer, you can continue with these next steps. When running the provided launches, make sure to the launch them by right clicking on the launch in the Project Explorer pane, and not by using the Run -> Debug As drop down (this is a problem with the feature based launches dropin).

Launch Error

Should you experience a launch error when running one of the launches, the easiest work-around is to leave eclipse running and launch the ./gradlew launches task from a terminal. This redeploys the launches and fixes problems that can occur when initializing a new eclipse environment with certain editions of eclipse. Once the launches have been copied again, continue with step 1 below.

1. First, launch the Create Development Environment Database Launch. This is necessary for creating a new database which is compatible with the new sdk version.

This will usually take a considerable amount of time to run. However, after a few seconds, a JUnit Tab should open up in the bottom pane, showing the progress of the unit tests being run. If this isn't the case, stop the execution and re-run it. Sometimes, a few tries are required until the tests are properly launched.

Ignore the numerous execptions in the console, and just let all 3 tests run to completion.

This will have created an uninitialized development environment database. To complete the setup process, continue with step 2.

2. Next, launch the Launch Development Environment launch in the same manner as the previous launch.

You should be familiar with the console output appearing, as it is practically the same as when launching an environment using the jazz development environment. As per usual, give it some time to spin up.

You can now connect to https://localhost:7443/jazz/. Accept the self signed certificate to continue.

Now, you should be greeted by the familiar jazz logon screen. Log in with the TestJazzAdmin1 / TestJazzAdmin1 credentials. We are now nearly done.

If you wish, you can now create a default project area and deploy the predefined process templates if you want to make these available for your users.

Once you have configured everything to your liking, you can just terminate the jetty server from within eclipse, and close eclipse. Then, continue with the release task.

Release Task

Make sure you have quit the running eclipse instance. We are now nearly done with preparing a new release. All files have been generated, and a new database has been created. This last step automates making this new configuration compatible with the jazz development environment, and thus making it unaware of any of your local machine configuration. You have the choice of either running the release task with or without the deploy flag set. Running it without the deploy flag will create all necessary files, but will not automatically copy them to the tool folder, but instead keeping them local to the jde/dev/ folder. This can sometimes be useful for first reviewing what has been generated. However, in this example, we will assume that everything has worked as desired, and we will also deploy the new configuration.

 ➜  ./gradlew release --deploy
Starting a Gradle Daemon, 2 incompatible Daemons could not be reused, use --status for details

> Task :release

As a final step, the release task will delete any version specific files in the jde/dev folder, so that a new, clean release will be created the next time it is necessary to do so. This can sometimes cause file or directory exceptions, but these can be ignored.

Preparing a Pull Request

Check the git status of your jazz development environment repository. You should see two new files, one inside tool/db_presets and one inside tool/sdk_files. Manually review the new sdk_files.cfg file for any weird paths. There have been some cases, so far only running windows, where the cleaning up of file paths didn't work correctly for all files listed in the configuration. These will be obvious by just giving the file a quick glance. If everything seems fine, create a new branch and initiate a pull request on GitHub to make this new configuration available to all users.

Appendix

Setting up the target platform

1. Open Window -> Preferences
2. Filter for target platform
3. Select "Nothing: Start with an empty target definition"
4. Choose a name, preferably rtc-sdk, and click Add...
5. Select Directory and click next
6. Browse to the correct directory inside the dev/initialize folder and click next
7. Activate the new target platform and confirm by clicking Apply and Close
8. Finally, add all the plugins of the target platform to the java search by clicking the appropriate button in the plug-in view.

If none of this helped, it's a case of eclipse not having a good day. Run ./gradlew ideClean and then run ./gradlew ide again. Sometimes, a few tries of this are required to get eclipse in the mood of correctly configuring everything. I assume this has to do with the osgi-loader and the non-deterministic nature of the order in which plugins are loaded.