Monday, January 7, 2013

Tycho build 6: Building products

Now that we can build almost everything, there is just one step missing: building an RCP application.

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: Convert required projects

Our example product has additional dependencies to com.codeandme.tycho.product and com.codeandme.tycho.product.feature which are not part of our maven build yet. To build our product we need to convert them first.

So convert com.codeandme.tycho.product to an eclipse-plugin and com.codeandme.tycho.product.feature to an eclipse-feature. Afterwards add both of them to our releng pom file. Nothing new so far.

Verify that your build works before proceeding.

Step 2: Create a project for our product

Create a new General/Project called com.codeandme.tycho.releng.product. Convert it to a maven project with Packaging set to eclipse-repository. Add the new project to our releng pom file as a module like we did for all the other projects.

Now move the file com.codeandme.tycho.product/Tycho.product to the root folder of our newly created project. Tycho will not pick up product files by default, so we need to adjust our com.codeandme.tycho.releng.product/pom.xml file a little. Add the following section within the project node:
 <build>
  <plugins>
   <plugin>
    <groupId>org.eclipse.tycho</groupId>
    <artifactId>tycho-p2-director-plugin</artifactId>
    <version>${tycho.version}</version>
    <executions>
     <execution>
      <!-- install the product using the p2 director -->
      <id>materialize-products</id>
      <goals>
       <goal>materialize-products</goal>
      </goals>
     </execution>
     <execution>
      <!-- create zip file with the installed product -->
      <id>archive-products</id>
      <goals>
       <goal>archive-products</goal>
      </goals>
     </execution>
    </executions>
   </plugin>
  </plugins>
 </build>

Step 3: Set start levels of your product bundles

There is one more step to take before we can run the build. It seems that PDE build (the thing that runs when you export an RCP product) adds some magic regarding bundle start levels. In fact it adjusts some autostart settings which we need to teach tycho manually.

Open your product definition file and switch to the Configuration tab. Use the Add Recommended button to populate plug-ins with their according start levels.



Save your product and start the build process. You should find your product in com.codeandme.tycho.releng.product/target/products/tycho.product/win32/win32/x86. There will also be a zipped version available in the target/products folder.

If you have problems with the startup levels for your build, then use the Eclipse Product export wizard from the Overview tab of your product file. Switch to the folder where you exported your product to and open the file configuration/org.eclipse.equinox.simpleconfigurator/bundles.info. Each line holds an entry of type

bundle_name,version,location,startlevel,autostart

Find all bundles where autostart is set to true and add them in your product configuration file with their according start levels.

Optional: Adding p2.inf files

If you want to add additional p2 information to your product build, place your p2 file in the same folder as your project file and name it <project_name>.p2.inf.

Eg. create a file com.codeandme.tycho.releng.product/Tycho.p2.inf with following content to add the Mars repository to the preconfigured update sites:

instructions.configure=\
org.eclipse.equinox.p2.touchpoint.eclipse.addRepository(type:0,location:http${#58}//download.eclipse.org/releases/mars,name:Mars);\
org.eclipse.equinox.p2.touchpoint.eclipse.addRepository(type:1,location:http${#58}//download.eclipse.org/releases/mars,name:Mars);

Optional: Build for multiple platforms

Adding another platform is simple: just ad a new environment to your master pom file:
      <environment>
       <os>macosx</os>
       <ws>cocoa</ws>
       <arch>x86_64</arch>
      </environment>
Eclipse help provides a full list of environment variables.

Optional: Adding icons to your product

When adding program icons in your product file the Browse... button will use an absolute path to your .ico file.


Unfortunately the tycho build will not be able to pick up the image that way and report:
Error - 7 icon(s) not replaced in <some path>\launcher.exe using
<some other path>\com.example.tycho.releng.product\images\your_icon.ico
To fix this use a path relative to your product definition file. For the example in the screenshot this would be images/my_product.ico.

More information on icons is covered in this stacktrace topic.

16 comments:

  1. I just switched to building my Eclipse product using Tycho and this is a really great tutorial, thanks for writing it.

    When I build my product, .eclipseproduct is generated. How can customize this file to my product? Right now, all I get are default value:

    name=Eclipse Platform
    id=org.eclipse.platform
    version=3.7.0

    In my product feature's POM I have tycho-packaing-plugin defined: http://pastebin.com/LbX1fgLG. I thought defining product would take care of that. In fact looking at .eclipseproduct file during various stages of the build I do see .eclipseproduct getting populated with my product id, but in final product it's gone.

    Thanks!

    ReplyDelete
    Replies
    1. Before I reade your comment I was completely unaware of this file. You might want to ask this question on the tycho users mailing list

      Delete
  2. Hi Christian,

    the best Tycho-tutorial I found, thanks for writing it!

    I encountered an issue when running the build after adding the product. Tycho is complaining about "Duplicate Reactor IUs":

    de.jmware.myproject.product 1.0.0 => [/sourcefolder/de.jmware.myproject.product, /sourcefolder/de.jmware.myproject.parent.product]

    The second project is the one I added following your tutorial (Section 9 "Building Products").

    I googled around but didn't found really helpful comments on this error. Seems that the Reactor UIs are built on artifactid and version, but these two are different in the projects mentioned above.

    Do you know how to solve this issue?

    Thanks in advance, Jens

    ReplyDelete
    Replies
    1. Ok, I found the error: product_id in product definition file was the same as the artifactid.
      Greets, Jens

      Delete
    2. Thanks for sharing this solution. I was not aware of this problem either.

      Delete
  3. Thanks for the hints about start levels. This probably saved me some hours...

    ReplyDelete
  4. Hi,
    First of all, I thank you for this tuto which helped me to begin whith Tycho.

    However , I still have some questions.

    Can tycho build multiple products ?
    Eg : I have 2 products , each has 1 feature which has 1 plugin.
    and I dont understand where I have to write :




    org.eclipse.tycho
    tycho-p2-director-plugin
    ${tycho-version}



    materialize-products

    materialize-products




    archive-products

    archive-products








    Moreover, I'm using tycho 0.18 with Maven 3.0.3 and eclipse Indigo 3.xx with offline mode ( can"t access web to download packages). But I have stored a lot of them which is not a problem to run my project. I just wanted to highlight that I need answers related to that "problem". :)

    Thank you.

    ReplyDelete
    Replies
    1. > Can tycho build multiple products ?
      Yes, it can. Create 2 independent product builds that work on their own. Then create a new project, convert it to maven and set packaging to pom. Then add your 2 product builds as modules to that pom. If you build it, it will build its 2 modules, which in fact are your independent product builds.

      > (I guess you tried to repost the xml snippet)
      This will go to com.example.tycho.releng.product/pom.xml. Best download the sources, import into your workspace and give it a try. You can browse all the files and see, how thigs fit together.

      Regarding offline mode:
      This will work if you have all your maven definitions and plugin dependencies available on your local machine (or network). As a general hint I would suggest to try to run this setup online first and then try to run it in offline mode.

      Delete
  5. Hello,
    thanks for this good guidline for tycho users.
    I have some questions :
    is there any convention on how to add p2.inf files ?
    what do you mean exactly by in ".p2.inf".?
    Thanks in advance

    ReplyDelete
    Replies
    1. I find the answer :
      The p2.inf file for a product definition example.product needs to be called example.p2.inf
      http://wiki.eclipse.org/Tycho/Packaging_Types#eclipse-repository
      Thanks again for this helpfull guideline :)

      Delete
    2. Thanks for sharing your answer here in the comments. As written in the blog your file needs to be named like this: <project_name>.p2.inf. Additionally it has to be placed in the same folder as your product definition file.

      Delete
  6. Hello,
    I have an other question please :
    I want to install a p2 repository (a third part plugins) in my final product :
    How can I do it ?
    is there a way using p2.inf ?
    Thanks in advance

    ReplyDelete
    Replies
    1. If you want to add a new update site to your product, please read the tutorial and find the answer in the section: Optional: Adding p2.inf files
      If you intend to install additional features you might do that with p2.inf files too, but I can't help you with the syntax for that.

      Delete
    2. Yes, I’m trying to install additional feature in eclipse with tycho build system.

      I added a product.p2.inf
      instructions.configure=installFeature(feature:org.eclipse.help.feature.group,featureId:default,version:default);

      Unfortunately the build fails:

      An error occurred while configuring the installed items
      session context was:(profile=DefaultProfile, phase=org.eclipse.equinox.internal.p2.engine.phases.Configure, operand=null --> [R]sample.product 1.0.0.201211220827, action=org.eclipse.equinox.internal.p2.touchpoint.eclipse.actions.InstallFeatureAction).
      Installable unit contains no artifacts: [R]sample.product 1.0.0.201211220827.

      Any help is welcome
      Thanks in advance,
      Maherzia

      Delete
  7. I am following your tutorial, using Kepler and Tycho 0.20.

    Everything works great until Chapter 6 - Building products. I am getting the following errors:
    [ERROR] Cannot resolve project dependencies:
    [ERROR] Software being installed: tycho.product 1.0.0.qualifier
    [ERROR] Missing requirement: tycho.product 1.0.0.qualifier requires 'com.example.tycho.product.feature.feature.group 0.0.0' but it could not be found

    Any ideas on what I may be doing wrong?

    ReplyDelete
    Replies
    1. I just checked out the example sources and build it successfully with tycho 0.21. Seems if you have maven 3.1 or higher you have to upgrade tycho to at least 0.18.0

      Delete