## Chapter 4. Compiling, Running, Debugging CSS

End users of CSS, i.e. people who run CSS on their office computer, should not have to compile CSS. They can down-load a version of CSS that is already configured for use in offices at their site from a local web site, and updates to CSS will automatically be down-loaded from that same web site.

To reach that stage, somebody at each institute that uses CSS obviously needs to prepare such a local down-load site, compile CSS with suitable settings and place the binaries on the web site. Compilation from sources is also required for those parts of CSS that the end-user does not see: Archive Engine, Alarm Server and tools to configure the archive and alarm system.

Fundamentally, the compilation of sources into stand-alone RCP products that you can then deploy onto other computers is easy:

1. Get Java and Eclipse
2. Get the CSS source code
3. Start Eclipse, import the sources
4. Open the *.product file for CSS, ArchiveEngine, ... and Export as a stand-alone binary.

Instead of going to the last step, i.e. exporting a product from within the Eclipse Integrated Development Environment (IDE) into a deployable product, you have more options.

While you are still developing and testing the version of CSS that you assemble for use at your site, you can run the product within the IDE. You can execute it without first exporting it into a stand-alone binary. Running a product within the IDE is the preferred method during development because it allows full source code debugging and minimizes the turn-around time from editing the code to executing the product. This is also what you should do when first trying to run CSS from source code.

Once the product is acceptable for use at your site, you export it from the IDE and install the result on the desired computers. This is what you typically do for tools like the Archive Engine, Alarm Handler or other non-end-user tools: Export and install.

While the product export from the IDE is initially very convenient, it remains a manual process. The Headless Build of a CSS product is a script-driven process that can automate the product compilation. It can also be used for automated integration builds. As mentioned in the section called “Java, Eclipse, RCP”, Eclipse products are operating system specific. Eventually, most sites will implement a headless built for their primary end-user products, because automated product generation is more repeatable, especially when creating several products for various operating systems. As a result of a headless build you typically get not only the binary products, like CSS for your site for Windows and Linux in 32 and 64 bit versions. In addition, you get a repository from which existing CSS products that are already installed at your site can down-load updates.

## Prerequisites

You will need

• Java Development Kit (JDK). It should be the JDK, not just a java Runtime Environment (JRE). It should be the Sun/Oracle or Apple JDK. OpenJDK, the GNU Compiler for the Java (GCJ) and other environments are currently not fully compatible with the Sun/Oracle JDK.
• Eclipse IDE for RCP/Plugin Developers. This has recently been called Eclipse for RCP and RAP Developers. Other versions like Eclipse IDE for Java EE Developers can be very useful if you also plan to do Web/Tomcat type of work, but the RCP version of the Eclipse IDE is the one that includes the full RCP source code and online help.

Both the JDK and the RCP IDE might have to be of a specific version, ask other CSS developers for the currently supported versions. At the time of this writing it has to be Java Version 1.7 also known as Java 7, and Eclipse 3.7.2.

## Obtaining the Source Code

For your first steps in CSS, it might be best to obtain a snapshot of the sources from one of the CSS sites. Such a snapshot will include what you need to build the products used at that site. When you access the CSS source repository, you can see the latest version of all sources from all CSS sites, which can be overwhelming.

To obtain a source snapshot, follow the links to collaborator sites on http://sourceforge.net/apps/trac/cs-studio/wiki and look for their source down-load.

The complete CSS sources are in a shared GitHub repository using the GIT version control system. Source Forge holds the project web site is http://cs-studio.sourceforge.net/ You can view the sources here: https://github.com/ControlSystemStudio/cs-studio

To work on the CSS source code, i.e. to be able to submit changes, several steps are necessary:

1. Obtain GitHub account.
2. Contact one of the CSS developers to gain write access to the repository.
3. Become familiar with the GIT version control system.

For details refer to the CSS wiki at http://sourceforge.net/apps/trac/cs-studio/wiki.

In the following, we assume you are either already familiar with working on a GitHub-hosted project, or you obtained a snapshot of the source code by other means, for example via down-load from a site that uses CSS. If you down-load the complete source code from the repository, you will receive a directory tree similar to this:

core/features/org.csstudio.core.feature
core/features/org.csstudio. ... .feature
core/plugins/org.csstudio.data
core/plugins/org.csstudio.logging
core/plugins/org.csstudio...
applications/features/org.csstudio.opibuilder.feature
applications/features/org.csstudio. ... .feature
applications/plugins/org.csstudio.opibuilder
applications/plugins/org.csstudio.sds
applications/plugins/org.csstudio.trends.databrowser2
products/NSLS2/plugins/...
products/NSLS2/...
products/SNS/plugins/...
products/SNS/product/org.csstudio.basic.epics.product
built/...


The source code is roughly organized into

• core plugins and features that are shared by many if not all sites that use CSS
• applications plugins and features that are several sites use
• product code that is specific to a site like NSLS2 or SNS

If on the other hand you unpack a source code snapshot from a specific site, the result might be a flat directory including only those sources used to build that site's products:

org.csstudio.data
org.csstudio.logging
org.csstudio...
org.csstudio.opibuilder.feature
org.csstudio.opibuilder
org.csstudio.trends.databrowser2
org.csstudio.basic.epics.product


## IDE Example

Running any Eclipse RCP product from the Eclipse IDE is fundamentally simple: Open the product definition file, click Launch ..., done. The most difficult part is the initial Workspace setup.

When you start the Eclipse IDE for the first time, you will be prompted for a Workspace. This is the directory where Eclipse keeps configuration parameters, for example your compiler settings, in a .metadata subdirectory. The Workspace is not necessarily the same directory that holds the source files. Eclipse will in fact not recognize source files that are simply placed in the Workspace directory on your disk. Your source files need to be imported into the workspace to be recognized by Eclipse.

In the following, we assume that you have the sources in a directory like /usr/fred/CSS/Sources, while your workspace is a separate directory /usr/fred/CSS/Workspace. To import the sources into the workspace:

• In the IDE, select the menu File/Import..., General, Existing Projects into Workspace.
• As a root directory, select /usr/fred/CSS/Sources.
• Do not check the option Copy projects into workspace!
• By default all the plugins on the disk will be selected. You can leave them selected, or select only specific plugins as described below.
• Press Finish.

If you import from a source snapshot used by a CSS site, that snapshot might be limited to the plugins that the site-specific products use, and you can simply import all plugins. On the other hand, if you import from a full source repository checkout, you might want to un-select plugins that you know you will not need because otherwise you will end up with a workspace that is confusingly huge, even though you at best need only half of the plugins in there.

The problem might be that you have initially no idea which plugins you actually need. You can leave them all selected, then later remove those from the workspace that you find not to be needed for your products. When deleting plugin projects from the workspace, do not check the option to Delete project contents on disk which would delete the actual files. Instead, only delete the project from the workspace, but leave it on the disk and thus also in the software repository.

If you start with an initial selection of plugins that you assume you might need, look for errors about missing plugin dependencies, then import the missing plugins. Though this will initially require some trial and error, it might in the end be the most convenient way.

The Eclipse Project Explorer should look similar to Figure 4.2, “Eclipse Project Explorer”. It shows a flat list of plugins, even if the source directory tree has the plugins arranged into sub-directories like core or applications. It may take some time for Eclipse to compile all the sources. There should be no errors, i.e. in the package explorer there should be no red marks on any plugin in the Project Explorer.

Next you open one of the *.product files, for example

org.cs.studio.basic.epics.product/CSS.product

You can use the Eclipse Search, File menu to locate all available product files as shown in Figure 4.3, “Locating all Product Files”

When you open an Eclipse product file, it will be displayed as per Figure 4.4, “Eclipse Product Editor”. In the Overview tab, first press Synchronize, then press Launch an Eclipse Application to run the product from within the IDE. The product should start up.

In the case of the Archive Engine it might soon exit with an error message indicating that it requires more command-line arguments. We will later describe how to export products from the IDE into standalone executables, and with such an exported command-line tool it will of course be trivial to provide command-line arguments when invoking the tool from the shell.

During development and initial testing, though, it can be more convenient to execute CSS products from within the IDE. To add command-line arguments to products executed in the IDE, invoke the menu Run, Run Configurations... Locate the configuration for the product, open its Arguments tab. The Program Arguments section may already contain entries like -os \${target.os}. Add your desired command-line arguments to the end of the program arguments.

When running a product from within the IDE for the first time, the main goal is that the product should start. It may then stop because of missing command line arguments, but there should be no errors regarding missing plugins or compilation problems.

If the product does not start up, and instead you get an error like Product ....could not be found or Missing required bundle ..., it can be helpful to open the menu Run, Run Configurations... Locate the configuration that was automatically created when you tried to launch the product. On the Plug-ins tab, press Validate Plug-Ins. It should give a list of unresolved plugins, i.e. missing dependencies.

If you downloaded a consistent set of sources, you should have the missing plugins, but maybe you did not import them into the workspace. Import them, them add them to the run configuration by either manually selecting them or via the button Add Required Plug-Ins.

If you cannot find the missing plugins, there are usually two scenarios: The missing plugins are part of Eclipse, and you are using a version of Eclipse that is not compatible with the sources. For example, some plugin code may depend on org.eclipse.core.runtime version 3.7, but you are using Eclipse 3.5 which is too old. The other scenario would be that you obtained an inconsistent snapshot of the sources where some part is simply missing. In that case you probably need to contact the maintainer of the CSS product to determine why the product configuration has an error.

If you get the product to run: Congratulations! Almost as easy as running the product is debugging it: Instead of running the product again from the menu Run, Run History, you select Run, Debug History to start the product in debug mode. You can browse the source code, set breakpoints by double-clicking at the start of a source line, then step through the code from the breakpoint on.

## JUnit Tests, Headless JUnit Tests

The Eclipse IDE has good support for executing JUnit tests and test-driven development in general. You can start many programming tasks by first implementing the JUnit test, using the IDE Quick Fix feature to create skeletons for the required classes and interfaces, which you then fill with the actual code until the test passes.

You will find several JUnit tests in the CSS plugin code because a lot of it was implemented in a test-driven fashion. These classes are often found in a test/ source folder, and the source files will be named *Test.java or *Demo.java.

To execute a JUnit test, you simply right-click on the class file in the Project Navigator and select Run As, JUnit Test. Some tests will need configuration files to specify database URLs or other site-specific parameters. Refer to comments in the source code for details.

Eclipse supports a special type of JUnit test to allow testing within the Eclipse runtime environment. This is necessary for tests that depend on the Eclipse plugin registry and preference system. Tests that require the plug-in runtime should be in source files named *PluginTest.java or *HeadlessTest.java. To execute them, select Run As, JUnit Plug-in Test from the file context menu.

When you invoke such a JUnit Plug-in Test for the first time, the IDE will create a run configuration that loads all the plugins found in your workspace. If the plugin containing your test refers to Eclipse user interface plugins, the plugin test configuration will in addition start an instance of the complete Eclipse IDE with all your workspace plugins, then execute the test. This can take a long time and be overkill for what you want to test.

A Headless plugin test is a test that requires the Eclipse plugin runtime environment but not the complete IDE user interface. Such test source files are typically named *HeadlessTest.java. To invoke such a test, you can once execute it via Run As, JUnit Plug-in Test to create the basic run configuration, but then you should edit it as follows:

• Menu Run, Run Configurations...
• Locate the JUnit Plug-in Test that was created for your headless test.
• On the Main tab, select Run an application with the option [No Application] - Headless Mode.

This will significantly reduce the startup time of your test because you avoid a copy of the Eclipse IDE.

• In the Arguments tab, you might need to add a program argument -pluginCustomization /path/to/your/settings.ini if your test needs certain preference settings.

• In the Plug-ins tab, by default all plugins in your workspace will be included. You can change that to only include selected plug-ins, which can reduce the startup time and might also be necessary to test the behavior of your test in case it depends on certain other plugins being available or not.

## Product Export from IDE

End users of CSS cannot be expected to open the IDE, install the source code, and then run CSS from within the IDE. They need a product that executes from their start menu or a desktop link. One way to create such a standalone product is to export the product from the IDE.

To export a product, open the product file that was already shown in Figure 4.4, “Eclipse Product Editor” and press the Eclipse Product export wizard link in the Overview tab. This will open the Eclipse product export dialog, see Figure 4.5, “Product Export Dialog”, where you enter the following:

1. As a Root Directory, enter the name of the product, for example ArchiveEngine, CSS, ... You could include a version number, for example CSS-3.0.

Use only a directory name, no path! This is the name of the directory that will contain the generated executable and associated files.

2. Enter a Directory path where the exported product should be placed, for example /usr/fred/CSS/bin

Enter a full path for this option! In the end, the name from the previous option will be appended to this directory path, so your product will end up in a directory similar to /usr/fred/CSS/bin/CSS-3.0.

Also assert that the directory that you selected is empty! When you export a product into a directory that already contains a product, maybe an older version of the same product, Eclipse will attempt to add the new code to the existing content, similar to an online update of an existing product. That is probably not what you want, so export into a an empty directory.

3. You might want to un-check the option to Generate metadata repository
4. Finish

You should now have a directory like /usr/fred/CSS/bin/CSS-3.0 that contains a css executable. You can copy that directory to other computers and run it there. One method of deployment would be to offer a ZIP file of the exported product on a web page.

If you left the option to Generate metadata repository checked, Eclipse will generate also an update repository, see Chapter 17, Update Repository.

### Command-line Products for Windows

Command-line applications, in Eclipse called headless RCP applications, are invoked from a terminal window, i.e. the Linux shell, Mac OS X terminal, or Windows Command Prompt. They are configured via command-line arguments, and they print information to the terminal.

Note that there is currently a limitation for command-line products on Windows! Headless RCP applications work fine on Linux and Mac OS X, but in the Windows command line tool cmd.exe you will by default not see any output from headless RCP applications. The problem is related to the fact that Java for Windows includes both javaw.exe and java.exe because Windows distinguishes between GUI and console applications. javaw -version invoked in cmd.exe will not display any output, either.

Eclipse for Windows likewise includes launchers eclipse.exe and eclipsec.exe. Headless products like an ArchiveEngine, AlarmServer etc. should use eclipsec.exe as their launcher, but there is currently no way to specify this in the product configuration, see also the bug report on Support for exporting eclipsec.exe in RCP apps, https://bugs.eclipse.org/bugs/show_bug.cgi?id=185205.

For the time being, the only solution is to manually replace the generated launcher, for example AlarmServer.exe, with a copy of eclipsec.exe:

copy \path\to\eclipsec.exe AlarmServer.exe

After replacing the original executable with a copy of eclipsec.exe, you can invoke the AlarmServer.exe from within the Windows Command Prompt, and you will see its command line output inside the Command Prompt window. If you start the AlarmServer.exe via double-clicks from the Windows Explorer, i.e. not from within a Command Prompt, it will actually open a new Command Prompt in which it can then display command line output.

## Delta Pack, Cross-Platform Export

The product that you export from the IDE is by default limited to the operating system on which it was exported because of the OS-dependent launcher and SWT libraries, see the section called “Java, Eclipse, RCP”. To export code for different platforms, you need the Eclipse Delta Pack. With the Delta Pack installed, Eclipse on OS X can for example build products for Windows, Linux, and OS X. Same for Linux and Windows.

To obtain the delta pack:

2. Select Projects, Eclipse Project.
3. Select the version of Eclipse that you are using, for example 3.7.2.
4. Locate the Delta Pack, a file like eclipse-3.7.2-delta-pack.zip.

To use the delta pack:

1. Extract the delta pack archive into its own directory on disk. The result should be an eclipse directory with sub-directories plugins and features
2. Open the Target Platform preferences: Menu Preferences, Plug-in Development, Target Platform. The Preferences item is usually in the Windows menu, but for Mac OS X it is in the Eclipse menu.
3. Edit the active target. Add an Installation, using the path to the delta pack's eclipse directory.

When you now export a product from the IDE, there will be a new option Export to multiple platforms.

The Headless Build is eventually necessary for each site that periodically publishes CSS product updates. It automates the build process, guaranteeing that the products are indeed exported for each supported platform. It can also be used as part of a nightly or integration build.

A headless build, however, is more complicated to set up than the product export from the IDE. The headless build does not use the workspace nor the graphical IDE. Instead, it is command-line driven and expects to find all feature and plugin projects in subdirectories of the build directory which have to be named features respectively plugins.

This usually requires a shell script or a build file for ant to copy all feature and plugin projects that are part of your product into such a build directory layout. In addition, you need a file build.properties to specify which product or feature to build, which target architectures to use, and how to name the generated archive files.

For details, check the Eclipse online help for Headless Build, or refer to the scripts that other CSS sites use to build their products, which can be found in the build and products subdirectories of the CSS sources.

## Feature Patch

A side effect of the headless build and a P2-managed product is that it is no longer possible to simply replace plugins in a product with new versions. If you replace a plugin JAR file with a different version, even if the names exactly match, P2 will recognize the change because of checksums. It will refuse to load the modified plugin, because it was part of the original configuration. In the spirit of maintaining a well defined product with known content, this makes sense. Occasionally, however, it is a big nuisance: Fixes to small bugs are no longer possible via basic plugin updates. Instead, you have to create a new product by incrementing all version numbers, perform a complete headless build, then publish the new product and its repository on the update site.

A feature patch can be used to update only part of a product while maintaining full configuration control. Assume our current product contains a plugin org.csstudio.trends.databrowser2 with version number 3.0.1 that we intend to replace with a newer version 3.0.2. We need to determine which feature provides that plugin in the product-to-update, and we need to determine its exact version, including a possible date/time qualifier. If you do not know which feature provided the original plugin, search the files in the features subdirectory of the installed product. Assume we find that the plugin was provided as part of the feature

org.csstudio.trends.databrowser2.feature_3.0.1.20110715


Create a new Feature Patch project in the Eclipse IDE:

• As a project name you can for example use databrowser3.0.1.patch.
• In the Properties of feature being patched section of the project wizard enter the Feature ID of the original feature, i.e. org.csstudio.trends.databrowser2.feature.
• Under Feature Version be sure to enter the correct version that you intend to update, i.e. 3.0.1.20110715.
• Add the plugins that should be updated with the patch, i.e. org.csstudio.trends.databrowser2. The feature that we are patching might contain many more plugins, but in the patch we only include what we want to add or replace. Assert that the version numbers of all the plugins that you want to replace have been incremented from their installed version.

You can now export the feature patch, using an archive file like databrowser3.0.1.patch.zip as the target, and then use that ZIP file to install the patch into your product via the menu item Help, Install New Software... by adding the ZIP file to the available software sites.

As a result, the original org.csstudio.trends.databrowser2 plugin is replaced with the new one, while P2 remains fully aware of what version of which plugin was installed from where, so it will for example allow you to un-install the patch, or later add additional feature patches.