Jump to: navigation, search

Difference between revisions of "Orbit/Easy Bake Builds with Orbit Bundles"

 
(8 intermediate revisions by 3 users not shown)
Line 2: Line 2:
 
PDE build also supports checking out multiple versions of the same plugin. </p>
 
PDE build also supports checking out multiple versions of the same plugin. </p>
  
<br>
+
== IP ==
  
<p>Before starting, it is very important to note that you must still receive approval from the Eclipse Foundation before including any third party bundles in your build.
+
Before starting, it is very important to note that you must still receive approval from the Eclipse Foundation before including any third party bundles in your build.
See the [[Orbit_Faq | Orbit Faq]] and and [http://www.eclipse.org/orbit Orbit web page] for further information.</p>
+
  
<br>
+
See the [[Orbit_Faq | Orbit Faq]] and and [http://www.eclipse.org/orbit Orbit web page] for further information.
 +
 
 +
== Orbit builds ==
 +
 
 +
Each milestone, the Orbit team releases a milestone before the Eclipse team enters milestone week.  This allows the Eclipse team to step up to the latest Orbit milestone before starting our milestone week. See the [[Promotion%2C_Release%2C_and_Retention_Policies | Orbit Promotion, Release, and Retention Policies]] for more detail. The latest Orbit builds are [http://download.eclipse.org/tools/orbit/downloads/ available here].
 +
 
 +
Since everyone's build process is different, I invite other teams to add to this document with further information describing how they incorporated Orbit bundles in their builds.
 +
 
 +
== Include Orbit bundles into a feature ==
 +
 
 +
To edit your feature.xml easily, you'll probably need to have Orbit bundles you depend on available in your workspace. See [[Orbit Faq#How do I work with a bundle in Orbit?]] for more details.
 +
 
 +
<b>Include plugin information in a feature.xml file</b>. Assuming you want to redistribute the Orbit bundle, then you need to update an appropriate feature with information for the new Orbit bundle ... very similar to how you normally would, but there are two cases. <br />
 +
 
 +
Case of only one map entry for the bundle: In this case, you can use the familiar "3 zeros" for PDE to fill in the version it finds from the map file. For example,
 +
 
 +
<pre><nowiki>
 +
  <plugin
 +
        id="org.apache.commons.lang"
 +
        version="0.0.0"
 +
        unpack="false"/>
 +
</nowiki></pre>
 +
 
 +
Case of multiple versions in map file: This happens, for example, when someone includes the whole Orbit generated map file in their directory of map files, so then there will be multiple entries for some bundles. In this case, you need to specify the version you desire. For example
 +
 
 +
<pre><nowiki>
 +
  <plugin
 +
        id="org.apache.commons.lang"
 +
        version="2.3.0.qualifier"
 +
        unpack="false"/>
 +
</nowiki></pre>
 +
 
 +
 
 +
== Consume Orbit bundles during your build ==
  
 
The process that we use to consume the Orbit builds can be summarized in three simple steps:
 
The process that we use to consume the Orbit builds can be summarized in three simple steps:
<ol>
+
*<b>Use current pde build.</b> Use a recent copy of PDE build in your builder with support for fetching prebuilt bundles - 3.3 M6 is the first one this support appeared in.
<li> Use a recent copy of PDE build in your builder with support for fetching prebuilt bundles - 3.3 M6 is the latest.</li>
+
*<b>Add appropriate map information.</b>
<li> <ul> * Consume the Orbit map file directly by fetching it during your build process. The Orbit build process generates map files with the lists of bundles that produced with each build.
+
** Consume the Orbit map file directly by fetching it during your build process. The Orbit build process generates map files with the lists of bundles that produced with each build. For example, see the latest [http://download.eclipse.org/tools/orbit/downloads/ stable Orbit build] - there are links to the map files in CVS format or HTTP GET format.
For example, see the latest [http://download.eclipse.org/tools/orbit/downloads/ stable Orbit build] - there are links to the map files in CVS format or HTTP GET format.</ul>
+
** ''OR''
<p>
+
** Update your local map file entry with the path to the Orbit bundle.  The platform releng team has added an orbit.map to their map file project org.eclipse.releng/maps, see example [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.releng/maps/orbit.map?revision=1.12 orbit map]  The reason we don't consume the Orbit map directly yet is because we are migrating to Orbit bundles on a ongoing basis.  If we consumed the Orbit map file directly today, we would have duplicate locations for the several bundles which would cause build issues.  Once we have migrated completely to consuming all our third party libraries from Orbit, we plan to modify our build process to consume the Orbit map file directly and remove the orbit.map from our map file project.
OR
+
</p>
+
<ul> * Update your local map file entry with the path to the Orbit bundle.  The platform releng team has added an orbit.map to their map file project org.eclipse.releng/maps, see example [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.releng/maps/orbit.map?revision=1.12 orbit map]  The reason we don't consume the Orbit map directly yet is because we are migrating to Orbit bundles on a ongoing basis.  If we consumed the Orbit map file directly today, we would have duplicate locations for the several bundles which would cause build issues.  Once we have migrated completely to consuming all our third party libraries from Orbit, we plan to modify our build process to consume the Orbit map file directly and remove the orbit.map from our map file project.</ul>
+
  
<br>
+
== Include bundles in Packaging ==
  
<li> If you are adding a new bundle to your build, update the appropriate feature with information for the new Orbit bundle. </li>
+
You also need to set 'runPackager' to true. This is true whenever any pre-built binary bundles are to be included with your packaged builds. See [http://help.eclipse.org/ganymede/index.jsp?topic=/org.eclipse.pde.doc.user/reference/pde_builder_config.htm PDE Build Help] for more information.
</ol>
+
  
<br>
+
In order to have Orbit bundles included into your build result, you need to add the '''runPackager=true''' option to the build.properties you use for your build.
  
Each milestone, the Orbit team releases a milestone before the Eclipse team enters milestone week.  This allows the Eclipse team to step up to the latest Orbit milestone before starting our milestone week. See the [[Promotion%2C_Release%2C_and_Retention_Policies | Orbit Promotion, Release, and Retention Policies]] for more detail. The latest Orbit builds are [http://download.eclipse.org/tools/orbit/downloads/ available here].
+
== Advanced customization for signing and packing ==
  
<br>
+
In most cases, these options can be ignored.
  
Since everyone's build process is different, I invite other teams to add to this document with further information describing how they incorporated Orbit bundles in their builds.
+
Orbit bundles are already signed, so that you may prefer not re-sign them in your build process. If you run your sign task from a folder or a zip file, you can avoid to re-sign Orbit bundles by adding a '''pack.properties''' at the root of the folder or zip, and specify a '''sign.excluses''' and a '''pack.excludes''' option with the list of Orbit bundles.
 +
 
 +
See [[JarProcessor Options#pack.properties|JarProcessor documentation page]] for more details.
 +
 
 +
== See also ==
 +
 
 +
[http://www.eclipse.org/articles/Article-PDE-Automation/automation.html| Helpful documentation about Eclipse plugins build.]
 +
 
 +
[[Category:Orbit]]

Latest revision as of 14:28, 22 December 2010

During the Eclipse 3.3 M5 cycle, The Eclipse Team (Platform, JDT, PDE and Equinox) started consuming Orbit bundles in their builds. To facilitate this transition, PDE build was modified to support fetching builds from a http repository. See Bug 171869 Support for HTTP in map files PDE build also supports checking out multiple versions of the same plugin.

IP

Before starting, it is very important to note that you must still receive approval from the Eclipse Foundation before including any third party bundles in your build.

See the Orbit Faq and and Orbit web page for further information.

Orbit builds

Each milestone, the Orbit team releases a milestone before the Eclipse team enters milestone week. This allows the Eclipse team to step up to the latest Orbit milestone before starting our milestone week. See the Orbit Promotion, Release, and Retention Policies for more detail. The latest Orbit builds are available here.

Since everyone's build process is different, I invite other teams to add to this document with further information describing how they incorporated Orbit bundles in their builds.

Include Orbit bundles into a feature

To edit your feature.xml easily, you'll probably need to have Orbit bundles you depend on available in your workspace. See Orbit Faq#How do I work with a bundle in Orbit? for more details.

Include plugin information in a feature.xml file. Assuming you want to redistribute the Orbit bundle, then you need to update an appropriate feature with information for the new Orbit bundle ... very similar to how you normally would, but there are two cases.

Case of only one map entry for the bundle: In this case, you can use the familiar "3 zeros" for PDE to fill in the version it finds from the map file. For example,

   <plugin
         id="org.apache.commons.lang"
         version="0.0.0"
         unpack="false"/>

Case of multiple versions in map file: This happens, for example, when someone includes the whole Orbit generated map file in their directory of map files, so then there will be multiple entries for some bundles. In this case, you need to specify the version you desire. For example

   <plugin
         id="org.apache.commons.lang"
         version="2.3.0.qualifier"
         unpack="false"/>


Consume Orbit bundles during your build

The process that we use to consume the Orbit builds can be summarized in three simple steps:

  • Use current pde build. Use a recent copy of PDE build in your builder with support for fetching prebuilt bundles - 3.3 M6 is the first one this support appeared in.
  • Add appropriate map information.
    • Consume the Orbit map file directly by fetching it during your build process. The Orbit build process generates map files with the lists of bundles that produced with each build. For example, see the latest stable Orbit build - there are links to the map files in CVS format or HTTP GET format.
    • OR
    • Update your local map file entry with the path to the Orbit bundle. The platform releng team has added an orbit.map to their map file project org.eclipse.releng/maps, see example orbit map The reason we don't consume the Orbit map directly yet is because we are migrating to Orbit bundles on a ongoing basis. If we consumed the Orbit map file directly today, we would have duplicate locations for the several bundles which would cause build issues. Once we have migrated completely to consuming all our third party libraries from Orbit, we plan to modify our build process to consume the Orbit map file directly and remove the orbit.map from our map file project.

Include bundles in Packaging

You also need to set 'runPackager' to true. This is true whenever any pre-built binary bundles are to be included with your packaged builds. See PDE Build Help for more information.

In order to have Orbit bundles included into your build result, you need to add the runPackager=true option to the build.properties you use for your build.

Advanced customization for signing and packing

In most cases, these options can be ignored.

Orbit bundles are already signed, so that you may prefer not re-sign them in your build process. If you run your sign task from a folder or a zip file, you can avoid to re-sign Orbit bundles by adding a pack.properties at the root of the folder or zip, and specify a sign.excluses and a pack.excludes option with the list of Orbit bundles.

See JarProcessor documentation page for more details.

See also

Helpful documentation about Eclipse plugins build.