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:
- Get Java and Eclipse
- Get the CSS source code
- Start Eclipse, import the sources
- Open the
*.productfile 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.
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.
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 CSSapplicationsplugins and features that are several sites useproductcode 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 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.
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 Testthat was created for your headless test. -
On the
Maintab, selectRun an applicationwith 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
Argumentstab, you might need to add a program argument-pluginCustomization /path/to/your/settings.iniif your test needs certain preference settings. -
In the
Plug-instab, 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, for example
/usr/fred/CSS/binEnter 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.
- You might want to un-check the option to “Generate metadata repository”
- 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 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.
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:
- Goto the Downloads section on http://www.eclipse.org/.
- Select “Projects”, “Eclipse Project”.
- Select the version of Eclipse that you are using, for example 3.7.2.
- Locate the Delta Pack, a file like
eclipse-3.7.2-delta-pack.zip.
To use the delta pack:
- Extract the delta pack archive into its own directory on disk.
The result should be an
eclipsedirectory with sub-directoriespluginsandfeatures - Open the Target Platform preferences:
Menu
Preferences,Plug-in Development,Target Platform. The Preferences item is usually in theWindowsmenu, but for Mac OS X it is in theEclipsemenu. - Edit the active target. Add an “Installation”, using the path to the delta pack's
eclipsedirectory.
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.
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.