17.2. Provisioning GDA

General instructions for provisioning a GDA workspace with Oomph Designed to be applicable whether on a standard DLS workstation or an external machine. For external deployment read the Oomph configuration appendix first.

17.2.1. Requirements

For DLS workstations the requirements may be loaded from the module system:

module load java/21
module load oomph
module load maven
module load dasctools # for access to dev-inst & bl-inst scripts

17.2.2. Provisioning GDA for Development - Step by Step

  1. Ensure the correct java version is on the path (see note), the version can be checked with java -version

  2. Ensure Maven (mvn) is available on the path, e.g. mvn -version

  3. Start Oomph using dev-inst (at DLS), or optionally using eclipse-inst for non DLS machines

    dev-inst /scratch/gda-development

    Running dev-inst the first time may require some user input in relation to setting up shared Eclipse directories

  4. Initially Oomph may open in Simple mode scale75 In this case switch to Advanced mode which is accessed via the menu. Subsequent launches of Oomph will remember the desired mode.

  5. The product catalog will now be presented. There is only one product available (Eclipse IDE for RCP and RAP Developers). It is recommended to use the latest version available. Ensure the Java version/location is as expected. scale75

  6. Advance to the next page - the project catalog. This allows specification of the version of GDA (or other projects) to create a workspace for. scale75

  7. The next page will show a summary of Oomph’s variables. Most of these will not need any modification apart from the “Beamline Workspace identifier” which can be used to specify a single beamline workspace, or to import projects for all beamlines into the workspace. The “Installation folder name” may also be set to choose the name of the directory in which this workspace will be created, under the root install folder. scale75

  8. Advance to the final page which will show a summary of the bootstrap tasks that Oomph will perform to create an IDE. Choose Finish, which will begin the creation of the IDE and workspace. For first time installs there will be some additional dialogs requesting acceptance of licenses.

  9. Eclipse will then launch and you may now close the installation window.

  10. After a few seconds another, rather blank, Oomph variables dialog will appear in the IDE. Once dismissed Oomph will begin its provisioning tasks within the IDE which include cloning the repositories, importing the projects and setting the target platform. The perspective will be empty until the tasks to clone all the repositories has completed and product import has begun. scale75 To view the state press the spinning Oomph icon found on the bottom toolbar, if the Oomph task dialog has not opened automatically. scale75

  11. Once completed the workspace will start compiling and be ready for development. Often there will be remaining errors. These are suspected to result from race conditions and the complex interproject dependencies in the workspace. To resolve turn off “Build Automatically” (Project -> Build Automatically) and run a build with CTRL-B. Some errors may not disappear even after this. If they are plugin.xml schema errors they may be ignored or deleted, otherwise attempt CTRL-B again.

  12. To launch a product see Launching from the IDE.

  13. To build an exported product see Maven build

17.2.3. Provisioning GDA for Beamline deployment - Step by Step

The procedure for beamline deployment is similar to the development case. The main difference here is that there is less flexibility in configuring Oomph as we have to be careful to deploy things consistently across all beamlines, and maintaining a level of separation between different beamlines to ensure that any issues are confined to a small area.

The majority of this is specified by the bl-inst script, analogous to dev-inst.

  1. Set the BEAMLINE environment variable to the appropriate value e.g.

    export BEAMLINE=p45

    This is not required on beamline workstations as this is already set.

  2. Run bl-inst

  3. This will launch Oomph in a “virtual home” mode which will set the bundle pool to /dls_sw/$BEAMLINE/software/gda_versions/.p2/pool and cause Oomph/Eclipse to act as if /dls_sw/$BEAMLINE/software/gda_versions is the home directory.

  4. Proceed through steps as above following after dev-inst launch step. However take note on the Variables page to ensure that “Installation folder name” is set to a suitable value

17.2.3.1. Alternative procedure with no IDE

Depending on beamline development preference it might be the case that an IDE is not required. In this case GDA can be deployed without the use of Oomph.

This is an example of the commands required to achieve this:

# Change to deployment root for beamline
cd /dls_sw/p45/software/gda_versions

# Create deployment directory and workspace_git
mkdir -pv gda-9.32/workspace_git
cd gda-9.32/workspace_git

# Clone daq-aggregator & install Gerrit hook
git clone "ssh://gerrit.diamond.ac.uk:29418/daq/daq-aggregator" daq-aggregator.git\
&& (cd "daq-aggregator.git" && mkdir -p `git rev-parse --git-dir`/hooks/ && curl -Lo `git rev-parse --git-dir`/hooks/commit-msg https://gerrit.diamond.ac.uk/tools/hooks/commit-msg && chmod +x `git rev-parse --git-dir`/hooks/commit-msg)

# Switch to correct branch for deployment
cd daq-aggregator.git
git checkout gda-9.32

# Change back to workspace_git
cd ..

# Run clone-repositories.sh
daq-aggregator.git/clone-repositories.sh

This will result in a workspace_git that looks the same as if it had been created with Oomph with each repository checked out to the appropriate branch.

The products may now be built as described in Maven build.

17.2.4. Appendix: Oomph configuration

The standard Eclipse Installer (Oomph) contains a catalog of products and projects. The products available include the standard flavours of Eclipse e.g. Eclipse for Java Developers. The project catalog contains setup configurations for many Eclipse projects e.g. Egit, EMF, Tycho.

DLS has its own product and project catalog to contribute entries relevant for GDA development. These are enabled by passing ECF (Eclipse Communication Framework) based redirects into eclipse-inst as Java system properties. This uses Oomph’s redirectable product/project catalogs to allow the DLS catalogs to be made available.

Note that the DLS oomph/eclipse-inst module already has these redirects in place so no further action is required on a DLS workstation.

For a custom instance of Oomph the following lines should be appended to <OOMPH_INSTALL_ROOT>/eclipse-inst.ini (must be inserted after the -vmargs entry):

-Doomph.redirection.diamond=index:/uk.ac.diamond/->https://alfred.diamond.ac.uk/oomph/uk.ac.diamond/
-Doomph.redirection.diamondProjectCatalog=index:/redirectable.projects.setup->index:/uk.ac.diamond/DLSProjects.setup
-Doomph.redirection.diamondProductCatalog=index:/redirectable.products.setup->index:/uk.ac.diamond/DLSProducts.setup

Optionally these could be passed into the executable directly (possibly combined with an alias) in the following way:

eclipse-inst -vmargs -Doomph.redirection.diamond="index:/uk.ac.diamond/->https://alfred.diamond.ac.uk/oomph/uk.ac.diamond/" -Doomph.redirection.diamondProjectCatalog="index:/redirectable.projects.setup->index:/uk.ac.diamond/DLSProjects.setup" -Doomph.redirection.diamondProductCatalog="index:/redirectable.products.setup->index:/uk.ac.diamond/DLSProducts.setup"

In the Oomph dialogs for product and projects catalogs, the DLS entries might need to be made visible explicitly. The visible catalogs may be selected in the drop down located at the top right of the window:

scale75