Mini-tutorial: Exporting agents and apps from Eclipse


Originally posted by eickler on 2012-03-25 21:02:58

We currently rely a lot on Eclipse built-in features for the SDK, and this includes creating executable packages for software. However, I haven't found a good description on the web how to do this with Eclipse, so I thought a small tutorial would be generally interesting for Java developers on Cumulocity. I use MacOS packages as an example, but it should work in the same way for other OSs.

The procedure is a little bit of work initially, but once you are through, you can create executable packages with just a few clicks from Eclipse or even fully automated from a continuous integration tool via Maven Tycho. The high-level steps are:
  1. Check your project build files for completeness.
  2. Add a so-called "launcher" to your runtime, which provides the base for running your application. (These come usually with Eclipse and are hence not part of our current download.)
  3. Create an Eclipse product configuration file.
  4. Run the Eclipse export wizard to produce the executable (or use Maven Tycho in an automated build process).
  5. [/list:o] 1. Check build files Eclipse usually generates correct build files automatically. However, in case of web applications, the "WEB-INF" folder and the web artifacts (HTML files, icons) are missing.
    • In each of your web projects, open "".
    • Checkmark the "WEB-INF" folder and other web files in the "Binary Build" tree at the bottom left.
    • Save the files.
    • 2. Add launcher The easiest way that I have found is to copy the launchers from your existing Eclipse installation into a separate folder and use them from there. Alternatively, you can get the launchers from the Equinox SDK.
      • Create a folder and copy the generic launcher as well as the OS-specific part into the folder. In my case, the launchers had the names below. (Note that the OS-specific launcher is a folder in the example.)
      • Open "Preferences", "Plug-in Development", "Target Platform", select the Cumulocity runtime and edit it. Click "Add…", "Directory" and select the folder that you just copied the launchers into.
      • Open "Run", "Run Configurations…" and select the configuration that you have been using for testing. Add the launcher parts to it.
      • Check the configuration for correct start level and auto-start settings. For example, if you have created an agent bundle with an activator in it, it needs to have "auto-start" set to "true".
      • "Apply" and "Close".
      • 3. Create a product configuration
        • Create a general project with "New", "Project", "General", "Project", "Next" and give it a name. Click "Finish".
        • In the project, click "New" and "Product Configuration" (assuming the plug-in development perspective is enabled). Enter a file name for the product configuration, select "Use a launch configuration" and choose the configuration you used above in the drop down box. Click "Finish".
        • In the "Overview" tab, enter an ID ("com.mycomp.myproduct"), a version and a name. Make sure that both "Product" and "Application" are empty.
        • In the "Launching" tab, type a name into "Launcher Name". This is what the generated executable is going to be named. Save.
        • 4. Export the product After the setup is through, you can create a runnable package by clicking the "Export" icon on the top right of the editor, or by using the menu "Export", "Eclipse Product". When you open the export wizard for the first time
          • Type the name of the directory that will be created and will hold your package.
          • Unselect "Synchronize before exporting". Unselect "Generate metadata repository".
          • Select a directory where everything should go.
          • Click "Finish" and check the directory. You can now either start the native binary launcher (e.g., on MacOS, if you use "myapp" as launcher name above, there will be a "") or start java manually:
            java -Dosgi.noShutdown=true -Declipse.ignoreApp=true -jar plugins/org.eclipse.equinox.launcher_1.2.0.v20110502.jar  -consoleLog -console
            I hope this helps you to get an easier start. If someone is interested, I could also write a bit on automating Cumulocity builds with Tycho. Cheers, André
Have more questions? Submit a request