RTC Client Setup - quality-manager/onboarding GitHub Wiki

RTC (EWM) Client Setup

Download EWM

EMW is used for source control and managing defects, enhancements, and other work items. The version we are telling you to download is already integrated with Eclipse.

  1. Go to the web page for the EWM Client or optionally Install Eclipse and EWM Separately
  2. We recommend using 7.0.2 (latest iFix) to be able to connect to all required repositories
Note that if your EWM Client is too old or too new, it may not be able to connect to some of the servers
Note that this differs from the screencast.
  1. Click "All Downloads"
  2. Scroll to the "Plain .zip files" section
  3. Download "Client for Eclipse <version> IDE" for your platform
  4. Log in with your jazz login
  5. Read and agree to the terms
  6. Extract EWM into a directory of your choice.

Change the Eclipse Heap Size

The minimum (-Xms) and maximum (-Xmx) memory allocation pool or heap size for Eclipse is:

  • -Xms256m
  • -Xmx1024m

Source:

  • macOS: <Eclipse.app location>/Contents/Eclipse/eclipse.ini
  • Windows: <Eclipse installation location>/eclipse.ini

To improve performance, change the minimum/maximum heap sizes to:

  • -Xms1024m
  • -Xmx2048m

Add -clean to the Eclipse Start-up

Source:

  • macOS: <Eclipse.app location>/Contents/Eclipse/eclipse.ini
  • Windows: <Eclipse installation location>/eclipse.ini

To start Eclipse in clean mode, add the following to the eclipse.ini:

  • -clean

In clean mode, any cached data used by the OSGi framework and eclipse runtime will be wiped clean. This will clean the caches used to store bundle dependency resolution and eclipse extension registry data. Using this option will force eclipse to reinitialize these caches.

Set the Java Preferences in Eclipse

There are several Java preference to be changed in Eclipse. The Java preferences are required to align the RQM development environment with the RQM build environment (<compile log for a plug-in> >> Compiler Options), to detect build errors during development.

  1. Open Eclipse.

  2. Open Preferences (Window >> Preferences... (Windows) or Eclipse >> Preferences... (macOS)).

  3. Click on Java >> Compiler.

  4. Change the JDK Compliance >> Compiler compliance level for the current/maintenance release:

    Release Version JDK Version
    7.0.3 1.8
    7.0.2 1.8
    7.0.1 1.8
    7.0 1.8
    6.0.6.1 1.8
    6.0.6 1.7
    6.0.5 1.7
    6.0.4 1.7
    6.0.3 1.7
    6.0.2 1.6
    6.0.1 1.6
    6.0 1.6

  5. Click Apply.

  6. [Alternative] Click on Java >> Compiler >> Errors/Warnings.

  7. Change Unnecessary code >> Unused import to Error.

  8. Click Apply.

  9. Click on Java >> Editor >> Save Actions.

  10. Click Configure.

  11. Click Unnecessary Code.

  12. Click Remove unused imports.

  13. Click OK.

  14. Click Apply and Close.

Note: See the Java Information Manage (JIM) site for IBM/Oracle JDKs/JREs.

Change the Eclipse Encoding Type

The default encoding on Windows and on some versions of macOS is not what is used in our product, so must be changed.

  1. Open Eclipse
  2. Open Eclipse preferences (window, preferences)
  3. Search for encoding
  4. Click on Workspace
  5. Change encoding to UTF-8
  6. Click Apply, then OK

Optional Preferences

The following optional Eclipse preferences can be updated:

  1. Run/Debug >> Console >> Output buffer size >> Uncheck the box so that it does not limit the buffer size, otherwise, you may miss some entries in the console
  2. General >> Editors >> Text Editors >> Show line numbers
  3. General >> Web Browser >> External

Other Configurations

The following optional Eclipse configurations can be updated:

  1. When in debug mode, hovering over String variables (and also in the details pane when looking at variables), the default Eclipse configuration is to truncate the string after 10000 characters. To enlarge, in the Variables view in debug mode, select a variable, and right click in the details pane below, select "Max Length…​", and in the dialog up the value, or set to 0 for unlimited length.

  2. Eclipse Detail Formatters

Install Foundation tools

The copyright updater on save updates copyright information on files when you save them. Without this tool, it must be done manually. The feature based launch tool simplifies running various launch files (For more information, click here). The Target Reloader reloads the target platform when it is updated. This is a "foundation" on top of which QM is built.

  1. Open Eclipse
  2. Click Help
  3. Click Install New Software
  4. Click Add
  5. For name, put Foundation Dev Tools
  6. For location, put https://jazzweb.ratl.swg.usma.ibm.com/foundation/tools/devtools-updatesite/
  7. Uncheck Group Items by Category
  8. Select:
    • Copyright Updater on Save
    • Feature Based Launches
    • Target Reloader
  9. Click install

Optional Installs

  1. Repository Service Dependency Diagram
  2. Eclipse SpotBugs. For more information, see Using the SpotBugs Eclipse plugin.

Configure Copyright Updater on Save

Once the Copyright Updater on Save tool has been installed in your Eclipse client it must be configured.

  1. Open up the Eclipse preferences window and search for Save Actions
    • To navigate there through the UI click Window (Windows) or Eclipse (macOS) >> Preferences... > Java > Editor > Save Actions
  2. Check the "Perform the selected actions on save" checkbox
  3. Check the "Additional actions" checkbox
  4. Click on the configure
  5. Deselect the check box for the other tabs (including Remove redundant type arguments (1.7 or higher) in the Unnecessary Code tab) and only leave the Update IBM copyright to current year in the Copyright tab selected
  6. Click OK twice

Install Findbugs and EclEmma

Findbugs is a static code analysis tool used to find common bugs in code. For more information click here. EclEmma is a JUnit Code Coverage tool - it determines what code has been tested by unit tests. For more information click here

  1. Open Eclipse
  2. Click Help
  3. Click Install New Software
  4. Click Add
  5. For name, put Findbugs
  6. For location, put http://findbugs.cs.umd.edu/eclipse
  7. Select Findbugs
  8. Click install
  9. Read and agree to the terms of the agreement
  10. After installation of findbugs, return to Install New Software
  11. For name, put EclEmma
  12. For location, put http://update.eclemma.org/
  13. Click install
  14. Read and agree to the terms of the agreement
  15. Restart eclipse

Install Jazz DevOps Toolkit

These tools provide a feature to easily create patches that can be installed on running servers.

To download, see Install JDT Tools.

Install Commander Plugin

This is an optional plugin which offers an enhanced Eclipse Command Palette for increased productivity Install directly from within Eclipse using the Marketplace (search for Commander) or visit https://marketplace.eclipse.org/content/commander

Copying Jazz Team Favorites New Workspace

If you are creating a new workspace you may wish to preserve Favorites in the Team Artifacts tab. You will need to copy them from your previous install at:

.metadata/.plugins/com.ibm.team.foundation.rcp.core/favorites.xml

Install Eclipse Web Developer Tools

Install 'Eclipse Web Developer Tools' from the update site for the version of Eclipse installed (see https://wiki.eclipse.org/Eclipse_Project_Update_Sites). Typically, only Eclipse XML Editors and Tools and Eclipse Web Developer Tools are required. Note, this is not required if you have installed Eclipse IDE for Enterprise Java and Web Developers. For more information, see How do I install WTP?.

Installing Eclipse and EWM Separately

  1. Download the Eclipse 2022-03 R (4.23) (recommended Eclipse version for the EWM version) installer or package and select the Eclipse IDE for Enterprise Java Developers or Eclipse IDE for Enterprise Java and Web Developers packages.
  2. Download EWM 7.0.2 GA P2 Install Repository.
  3. Unzip/install/start Eclipse. Note, if you are on macOS and want to rename the Eclipse.app application, rename it before starting Eclipse for the first time. Tip: When setting up Eclipse/EWM for the first time, install all the new software before making any configuration changes to Eclipse/EWM.
  4. In Eclipse, click Help >> Install New Software... >> Add... >> Archive....
  5. Select the EWM (P2 Install Repository) zip file.
  6. Select Rational Team Concert Client (extend an Eclipse Installation) (RTC 6.0.6.1 or earlier) or IBM Engineering Workflow Management Client (extend an Eclipse Installation) (EWM 7.0 or later) to install.
  7. Download and install the latest EWM 7.0.2 iFix.

Troubleshooting

  1. If you are on macOS, running with Eclipse 2022-03 R (4.23) will cause EWM defect 551949: NullPointerException when opening the context menu on a work item comment in the Eclipse work item editor.
  2. If you are on macOS, Eclipse will sometimes not start and the The application "Eclipse.app" can't be opened. error dialog will be displayed. See Eclipse bug 578883 for more details, including a work-around.
  3. Defect 534742: Cannot run Eclipse Software Update.
  4. Unable to install Foundation Tools.
    • If you are unable to login to view the Foundation Tools it may be due to either the server being down, your credentials being incorrect, your permissions not being approved yet, or a combination of these. Check to make sure your credentials you supplied are correct or wait until the server is brought back up or your permissions being granted
    • If you are unable to see "Copyright Updater on Save", "Feature Based Launches", or "Target Reloader" make sure that you have unchecked the "group items by category" checkbox. If you have the "group items by category" checkbox unchecked make sure you have all required permissions.
  5. When installing/upgrading Eclipse on macOS (Monterey), use the Oracle JRE. See the Java Information Manage (JIM) site for IBM/Oracle JDKs/JREs. Alternatively, use one of the IBM Semeru Runtimes. To list of all Java versions installed on macOS: /usr/libexec/java_home -V
  6. If you do not have a 'X' button and/or a red button for the icon in the tabs in Eclipse, you will have to create a new workspace.
  7. When installing/upgrading Eclipse/EWM on macOS (Monterey), you may see one of the following issues:
    • Starting Eclipse: Failed to create the Java Virtual Machine
    • Logging into a Repository Connection in the Team Artifacts view: Could not get value of field private transient sun.util.calendar.BaseCalendar$Date java.util.Date.cdate in <date/time>

This issue is caused by Eclipse resolving the JRE packaged with Eclipse (for example, OpenJDK), which may not be a supported.

The solution is to uncomment the following line in /Applications/<Eclipse application name>/Contents/Info.plist:

<string>-vm</string><string>/Library/Java/JavaVirtualMachines/<correct JRE>/Contents/Home/bin/java</string>

To list of all Java versions installed on macOS: /usr/libexec/java_home -V

In addition, you may need to add the following to the /Applications/<Eclipse application name>/Contents/Eclipse/eclipse.ini file under --add-modules=ALL-SYSTEM:

--add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.util.concurrent=ALL-UNNAMED