Table of Contents
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:
*.productfile for CSS, ArchiveEngine, ... and “Export” as a stand-alone binary.
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.
You will need
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.
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:
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
coreplugins and features that are shared by many if not all sites that use CSS
applicationsplugins and features that are several sites use
productcode 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
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
This is the directory where Eclipse keeps configuration parameters, for example your compiler settings,
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
while your workspace is a separate directory
To import the sources into the workspace:
Existing Projects into Workspace.
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.
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
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
You can use the Eclipse
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”.
Overview tab, first 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
Locate the configuration for the product, open its “Arguments” tab.
The “Program Arguments” section may already contain entries like
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
Locate the configuration that was automatically created when you tried to launch the product.
Plug-ins tab, press
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
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.
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
To execute a JUnit test, you simply right-click on the class file in the
Project Navigator and select
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
To execute them, select
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.
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
To invoke such a test, you can once execute it via
JUnit Plug-in Test
to create the basic run configuration, but then you should edit it as follows:
JUnit Plug-in Testthat was created for your headless test.
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.
Arguments tab, you might need to add a program argument
if your test needs certain preference settings.
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.
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:
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.
Enter a Directory path where the exported product should be placed,
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
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.
You should now have a directory like
that contains a
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 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.
is related to the fact that Java for Windows includes both
java.exe because Windows distinguishes
between GUI and console applications.
javaw -version invoked in
will not display any output, either.
Eclipse for Windows likewise includes launchers
Headless products like an
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”,
For the time being, the only solution is to manually replace the generated launcher, for example
AlarmServer.exe, with a copy of
copy \path\to\eclipsec.exe AlarmServer.exe
After replacing the original executable with a copy of
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.
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:
To use the delta pack:
eclipsedirectory with sub-directories
Target Platform. The Preferences item is usually in the
Windowsmenu, but for Mac OS X it is in the
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
This usually requires a shell script or a build file for
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
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
subdirectories of the CSS sources.
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
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
of the installed product. Assume we find that the plugin was
provided as part of the feature
Create a new Feature Patch project in the Eclipse IDE:
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
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
Install New Software...
by adding the ZIP file to the available software sites.
As a result, the original
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.