Monday, January 7, 2013

Tycho build 8: Using a target platform

A target platform describes, which features and plug-ins are used to build your product. It further defines where to look for those components.

Using a target platform makes your build reproducible and therefore predictable. Try to use it right from the beginning of your product development.

Tycho Tutorials

For a list of all tycho related tutorials see Tycho Tutorials Overview

Source code for this tutorial is available on github as a single zip archive, as a Team Project Set or you can browse the files online.

Step 1: Creating a target platform

The target file editor in Eclipse is somewhat 'special'. It has its rough edges. If you would like to avoid them I strongly suggest to use the Target Platform Definition DSL and Generator from Mikael Barbero. You need to install it in your IDE, but it will ease your life, trust me. For the next steps I assume you installed the plugin.


Create a new General/Project named com.codeandme.tycho.releng.targetplatform. Now create a new file named com.codeandme.tycho.releng.targetplatform.tpd within that project. Set the content to:
target "Tycho Tutorial" with source requirements

location "http://download.eclipse.org/releases/mars/" eclipse-mars {
 org.eclipse.platform.feature.group
 org.eclipse.rcp.feature.group
 org.eclipse.jdt.feature.group
 org.eclipse.equinox.p2.discovery.feature.feature.group
 org.eclipse.equinox.executable.feature.group
}
After saving select the file in the Project Explorer and select Create Target Definition File from the context menu. A .target file will be generated for you. Now open the .target file in the Target Editor and wait for the components to be loaded. Afterwards click the link in the upper right corner Set as Target Platform to activate it.

A full workspace build is triggered by that action. If all your dependencies can be resolved you should see no error markers on our projects.

Make sure that your target file follows the naming scheme <project name>.target otherwise tycho will not be able to pick it up.

Step 2: Integrate in maven build

Convert the project to a maven project with Packaging set to eclipse-target-definition. Then add it to your master pom. Now we need to change the master pom a little: remove the repositories section as we want to use our target platform instead of the Mars repository. To activate the target definition in maven modify the existing plugin section:

   <plugin>
    <groupId>org.eclipse.tycho</groupId>
    <artifactId>target-platform-configuration</artifactId>
    <version>${tycho.version}</version>
    <configuration>
     <target>
      <artifact>
       <groupId>tycho_example</groupId>
       <artifactId>com.codeandme.tycho.releng.targetplatform</artifactId>
       <version>1.0.0-SNAPSHOT</version>
      </artifact>
     </target>
     <environments>
      <environment>
       <os>win32</os>
       <ws>win32</ws>
       <arch>x86</arch>
      </environment>
     </environments>
    </configuration>
   </plugin>
If you followed my previous tutorials you will only need to add the target section as the rest should already be part of your pom file. The target/artifact/artifactId node refers to the name of the project, that contains the target definition file.

Your build now uses the target definition.

Optional: Mirror settings for a target platform

The location line in tpd files takes an id as last parameter. In our example it is eclipse-mars. This is the id to refer to in your maven mirror settings. So point your mirrorOf parameter in your settings.xml file to eclipse-mars.

22 comments:

  1. Awesome series of articles. I was trying to follow your target-platform setup.

    I am able to run my parent pom and build my project successfully. But within Eclipse plugin-dependencies have been removed from my build-path cozing error in my plugin and product projects.

    i need your help to understand on how to get back plugin-dependencies from target during eclipse development.

    ReplyDelete
    Replies
    1. I hope that your plugin-dependencies were not removed. Neither tycho nor the target platform will do such a thing. I guess that your dependencies simply cannot be resolved anymore and you get a lot of error markers on your manifest files.
      First check that your target platform definition (your *.target file) contains all the features your plug-ins depend on. Afterwards check that the versions of your dependencies are within valid range. eg if you depend on somplugin-3.9.1 but your target platform provides only 3.8.100 then the resolution will fail.
      Download the sample project and have a look at the target configuration if you need an example.
      HTH

      Delete
  2. Christian,
    bonus question, where in the plugin zip file would I expect the URL's for the update sites that are supposed to be consulted for the target platforms? I can't find any in my zip file.

    Thanks in advance.

    ReplyDelete
    Replies
    1. the target platform provides all update sites directly in the target file. Tycho will only pick up p2 locations from the target file. So you should not have local directories in there.

      Delete
  3. Oh, my first question was not posted? Here again:

    I have an Eclipse plugin project that depends on the nebula grid component. I defined the nebula in my .target file pointing to the latest nebula release repo. Tycho treatment with target component, update component and target file configured. All is well and fine when I install the packaged plugin from .zip into Jun/Kepler well.

    But Luna fails with
    Missing requirement: Code Center Component Search 1.4.0.201503191841 (com.example.plugin 1.4.0.201503191841) requires 'bundle org.eclipse.nebula.widgets.grid 1.0.0' but it could not be found

    Any idea why that is? How to debug this situation? Any examples of the same complexity (plugin [not RCP] plus external p2 in target)?

    I'm stunned.
    P.S.: When I add the nebula update site to the list of update sites in Luna it installs just fine.

    ReplyDelete
    Replies
    1. You might try http://stackoverflow.com/questions/8254116/adding-update-site-urls-to-find-third-party-dependencies-during-install
      Does this help?

      Delete
  4. Hi, Really thanks for this tutorial. It saved me a lot of time. I've got question to you about Target, because something works incorrectly when I'm doing it like in your recipe. I'm trying to set up target for project that is using javafx-eclipse components. So in locations of my target should appear:
    http://download.eclipse.org/efxclipse/runtime-released/1.2.0/site
    and I thought, that should also appeared location that you mention in this article http://download.eclipse.org/releases/juno (or luna) with four features.
    Unfortunately when I'm doing it, during installation of the plugin I'm getting message that Eclipse cannot recognize org.eclipse.fx.ui.workbench3 (which I'm using in my plugin).

    By accident I have found solution for it. Instead of adding http://download.eclipse.org/releases/juno I'm adding ${eclipse_home} and everything starts working without any problems. Can you explain why ? It's my first contact with Maven and Tycho and I'm a little mixed with plenty of options and not clear documentation (tutorials) about this. Thanks.

    ReplyDelete
  5. Thank you, it is really good tutorial, especially for some people who deal with Maven and Tycho first time.
    Thank you for your good tutorial.

    ReplyDelete
  6. Hi,
    I tried to do exactly the same thing by following the tutorial step by step, but when I try to build my com.codeandme.tycho.plugin project I get the error : [ERROR] Internal error: java.lang.RuntimeException: Could not resolve target platform specification artifact tycho_example:com.codeandme.tycho.releng.targetplatform:target:1.0.0-SNAPSHOT -> [Help 1]
    can you help me solve this problem?

    ReplyDelete
    Replies
    1. I just imported the team project set and built it from scratch without problems. Did you try that? In case that fails, check that you are using a current version of maven (I was using the internal mvn from eclipse mars.1) and that your internt access is not blocked in any way (eg a proxy)

      Delete
    2. ok I just tried to import the whole project andbuild it from scratch and it worked. Thanks a lot.
      Now I have a more important question, which is actually the reason why I'm learning this, I need to use StringUtils (from org.apache.commons) in my com.codeandme.tycho.plugin project. So I added this to my .tpd file and created the target platform from it :

      location "http://download.eclipse.org/tools/orbit/downloads/drops/R20150519210750/repository/" mars-orbit {
      org.apache.commons.lang3
      }

      The build is successful but I still can't use StringUtils in my plugin code. Am I missing something?

      Delete
    3. Well you need to
      a) set the target platform, so your workspace can resolve the plugin
      b) add a plugin dependency from your plugin to o.a.commons.lang3

      Delete
    4. you mean add the dependency in the pom.xml or MANIFEST.MF?

      Delete
    5. In the manifest. pom only defines build time dependencies. But this is all standard eclipse stuff, you should find plenty tutorials out there for this.

      Delete
    6. thank you very much. it worked!

      Delete
    7. Hi again,
      I have another question: in the plugin I need to access an Oracle database, so I need to use the Oracle JDBC, do I have to add a dependency to the Oracle packages? if yes, does it go the same way as described in your previous answer?

      Delete
    8. This is really off topic here. You should have a look at some basic eclipse developer tutorials. Check out vogella.com

      Delete
  7. This comment has been removed by the author.

    ReplyDelete
  8. Hi,Thanks for a great tutorial.I have a question

    I have created a target definition file and setup my own target platform.But when I am running my product file,I am getting validation error before startup saying "Missing constraint :require bundle:org.eclipse.e4.ui.workbench,bundle version:1.5.1" though I have added it to the contents of target definition and I can clearly see it in contents.

    Please help me out how to handle this

    ReplyDelete
    Replies
    1. This is not related to tycho, but to launch configurations, right? So please check out the generated launch configuration for its included plugins. Did you also check that your run configuration contains the correct version of the e4.ui.workbench bundle?

      Delete
  9. Even years later, this tutorial proves to be very helpful. Thank you.

    While following these steps (and archive files), I noticed that Step 1 was missing the following: org.eclipse.equinox.executable.feature.group. It is included in the archive file but missing from the instructions.

    ReplyDelete