Skip to main content
Jump to: navigation, search

Difference between revisions of "Orbit/FAQ"

(Add FAQ entry for comparing entire builds to check for unintended consequences - see https://bugs.eclipse.org/bugs/show_bug.cgi?id=572370)
 
(2 intermediate revisions by 2 users not shown)
Line 13: Line 13:
  
 
# Find the Orbit build drop that you need here: http://download.eclipse.org/tools/orbit/downloads/
 
# Find the Orbit build drop that you need here: http://download.eclipse.org/tools/orbit/downloads/
# Add <tt>updateSite/<tt> to the URL of the drop. For example, for the drop in http://download.eclipse.org/tools/orbit/downloads/drops/S20101204061544/ the update site that you will use is: http://download.eclipse.org/tools/orbit/downloads/drops/S20101204061544/updateSite/
+
# Add <code>'repository'</code> to the URL of the drop. For example, for the drop in http://download.eclipse.org/tools/orbit/downloads/drops/R20200831200620/ the URL that you would use is: http://download.eclipse.org/tools/orbit/downloads/drops/R20200831200620/repository/
# Create a new Target Definition file, and add an Update Site location using the drop's update site URL.
+
# As most projects use CBI for building, you would simply ensure that the URL is included in the Target Platform configuration
# Make sure "Group by Category" is checked.
+
  
 
== Does Orbit replace or affect the Eclipse Foundation legal process? ==
 
== Does Orbit replace or affect the Eclipse Foundation legal process? ==
NO!  Orbit holds only libraries that have been approved by the standard legal process. Projects must still follow this process to request permission to use libraries in their releases.
+
NO!  Orbit holds only libraries that have been approved by the standard legal process.Projects must still follow this process to request permission to use libraries in their releases.
 
+
== If a library is approved for use in "all" projects, do I still have to go through the legal process? ==
+
Yes. All projects must request permission to use '''any''' third party libraries.  If the the library is already in Orbit, you can use a "Piggy back" CQ, naming the CQ number that is associated with the bundle.
+
  
 
== Do projects have to use the Orbit bundles? ==
 
== Do projects have to use the Orbit bundles? ==
Line 34: Line 30:
  
 
== How do I become a committer in Orbit? ==
 
== How do I become a committer in Orbit? ==
Orbit committers are already committers from other Eclipse projects that have a need for a third party library. These people come to Orbit with an approved library and propose to include it in Orbit. If they are not already a committer in Orbit and their project does not have any committers in Orbit, they can become a committer by agreeing to bundle and maintain the new library. Accordingly, they will then be responsible for the care and feeding of that library and the corresponding bundle. You should make your interest known on the [http://dev.eclipse.org/mailman/listinfo/orbit-dev Orbit mailing list].
+
It is possible to contribute libraries to Orbit without being a committer, in the same way one can contribute code to other projects. The contributions are essentially metadata files that generate the library at build time. For repeated maintenance of many different libraries, one can consider applying to become a committer.
 +
 
 +
Orbit committers are already committers from other Eclipse projects that have a need for a third party library. These people come to Orbit with an approved library and propose to include it in Orbit. If they are not already a committer in Orbit and their project does not have any committers in Orbit, they can become a committer by agreeing to bundle and maintain the new library. Accordingly, they will then be responsible for the care and feeding of that library and the corresponding bundle. You should make your interest known on the [http://dev.eclipse.org/mailman/listinfo/orbit-dev Orbit mailing list].
  
 
== How do you name bundles containing other people's code? ==
 
== How do you name bundles containing other people's code? ==
Line 44: Line 42:
  
 
== How does Orbit manage multiple versions of the same library?==
 
== How does Orbit manage multiple versions of the same library?==
Luckily OSGi supports multiple versions of the same bundle installed and running at the same time so this does not present any particular runtime problems.  At development time however there is a challenge of project naming.  Since the Eclipse convention has been to use the bundle symbolic name as the name of the project, there would be a conflict if two versions of the same project need to be in the workspace at the same time
+
Luckily OSGi supports multiple versions of the same bundle installed and running at the same time so this does not present any particular runtime problems.  At development time however there is a challenge of project naming.  Since the Eclipse convention has been to use the bundle symbolic name as the name of the project, there would be a conflict if two versions of the same project need to be in the workspace at the same time.
 
+
The initial direction here is to use a CVS branch for each version of a library.  So, for example, for javax.servlet there is version 2.3 and 2.4 of the library.  Correspondingly, there branches named v2_3 and v2_4 are created to hold the related content.  HEAD of the javax.servlet project is empty except for a readme.txt file indicating that all work is carried out in branches.
+
  
 
== How do I add something to Orbit? ==
 
== How do I add something to Orbit? ==
Line 52: Line 48:
  
 
== How is source managed/delivered? ==
 
== How is source managed/delivered? ==
We never recompile source for Orbit distribution, but do sometimes package it as a source bundle so it can be found while debugging or while reading the code or JavaDoc. For more information, see [[Orbit_Bundle_Checklist#Create_a_Source_Bundle| Create a Source Bundle]].
+
We generally package source bundles for usage while debugging or while reading the code or JavaDoc. For more information, see [[Orbit_Bundle_Checklist#Create_a_Source_Bundle| Create a Source Bundle]].
  
== How do I work with a bundle in Orbit? ==
+
== Do I raise a CQ against Orbit to contribute my 3rd-party lib? ==
Since all of the interesting orbit work is done in branches, working with an orbited bundle can be confusing to the first-time user. But just follow these simple steps and you'll have it checked out into your workspace in no time!
+
# Create a repository connection to the orbit repository (CVS URL is ''':pserver:anonymous@dev.eclipse.org/cvsroot/tools''').
+
# Navigate to ''HEAD/org.eclipse.orbit/'''<your_project>''' ''.
+
# Check your project out into your workspace.
+
# Note that the project will be empty. (this is ok)
+
# In the Navigator (or Package Explorer, etc) right-click on the project and choose ''Replace With -> Another Branch or Version...'' and select the branch that you want to work with. (the branch names are the versions)
+
  
== Should we use qualifiers in the bundle version? ==
+
First, you need to raise the CQ against your project in which you intend to use the 3rd-party software, so that your PMC can approve its use in that context. Orbit can file the initial CQ in cases where the project cannot do so.
Yes. We should add a qualifier as the 4th part of a bundle version. e.g. ''3.8.1.qualifier''.
+
  
If we have versions which already have 4 parts to them then we should pad the 4th segment to 2 digits. For instance: ''4.1.0.01_qualifier''.
+
See [[Adding_Bundles_to_Orbit#Before_You_Do_Anything|Adding Bundles to Orbit]] for more details.
  
== Do I raise a CQ against Orbit to contribute my 3rd-party lib? ==
+
== How do I tell if my change had unintended consequences? ==
First, you need to raise the CQ against your project in which you intend to use the 3rd-party software, so that your PMC can approve its use in that context.  Orbit and its PMC are not consumers of these bundles, so the initial CQ should not be on Orbit.
+
  
When your project's CQ is approved, then Orbit welcomes an add-to-orbit (ATO) CQ to host the bundle.
+
Sometime a change may need to be made to the build infrastructure, such as upgrading a maven plug-in version. (For example [https://git.eclipse.org/r/c/orbit/orbit-recipes/+/178466/1/releng/mavenparent/pom.xml this pom.xml change] for [https://bugs.eclipse.org/bugs/show_bug.cgi?id=572370 Bug 572370]) When this happens it can be hard to tell if there are unintended consequences. Here are some steps that may be useful to compare entire repositories: (I wrote this steps after running them, it may be that there are some small mistakes, please feel free to update the steps):
  
See [[Adding_Bundles_to_Orbit#Before_You_Do_Anything|Adding Bundles to Orbit]] for more details.
+
* Clone the orbit repo into two directories so that we can compare before and after the change.
 +
* In one of the repos, apply the change.
 +
* Run  <code>mvn clean verify</code> in both repos. This will build all the individual bundles, but won't publish them to the ~/.m2/repository. The individual p2 repos will be in each bundle in the the target/repository directory.
 +
* Unpack all the built jars so they can be diffed (in both repos), for example with <code>find $PWD -path '*target/repository/plugins*' -name '*\.jar' -print -exec sh -c 'mkdir -p $0-d ; cd $0-d ; jar xf $0' {} \;</code> which will create a -d directory for each jar next to the jar with said jar unpacked.
 +
* Compare the -d directories from the before and after directories <code>find . -path '*target/*plugins*/*-d' -name '*-d' | while read i; do diff --ignore-matching-lines '^#Sun Mar 28 1[45]:' --ignore-matching-lines 'Bnd-LastModified: 16169' -r $i ../orbit-recipes2/$i; done</code> There are many files with timestamps, those lines can be ignored with  <code>--ignore-matching-lines</code> with the regex updated for the date you have built locally.
 +
 
 +
The above diff command will produce the following output for the example listed, showing that only the intended change happened:
 +
 
 +
<pre>
 +
$ find . -path '*target/*plugins*/*-d' -name '*-d' | while read i; do diff --ignore-matching-lines '^#Sun Mar 28 1[45]:' --ignore-matching-lines 'Bnd-LastModified: 16169' -r $i ../orbit-recipes2/$i; done
 +
Only in ../orbit-recipes2/./jna/com.sun.jna_5.6.0/target/repository/plugins/com.sun.jna_5.6.0.v20200716-0148.jar-d/com/sun/jna: linux-x86-64
 +
Only in ./jna/com.sun.jna_5.6.0/target/repository/plugins/com.sun.jna_5.6.0.v20200716-0148.jar-d: libjnidispatch.so
 +
'''
 +
</pre>
  
 
[[Category: Orbit]]
 
[[Category: Orbit]]
 
[[Category: FAQ]]
 
[[Category: FAQ]]

Latest revision as of 18:31, 28 March 2021

What is Orbit?

Orbit is a project designed to be a repository for third party libraries that are approved for use in Eclipse projects and are to be used/distributed as bundles. If the incoming libraries are not already bundles then Orbit committers will work to create a bundle that is suitable for use in Eclipse projects.

Under what license(s) are the Orbit bundles distributed?

It varies, but the third party bundles in Orbit retain their original license, as described in their about.html files. For simplicity, any additions or changes to the artifact (such as the addition of manifest.mf file or manifest entries) are made available under the same license as the original artifact.

How to use an Orbit bundle in your Target Platform

  1. Find the Orbit build drop that you need here: http://download.eclipse.org/tools/orbit/downloads/
  2. Add 'repository' to the URL of the drop. For example, for the drop in http://download.eclipse.org/tools/orbit/downloads/drops/R20200831200620/ the URL that you would use is: http://download.eclipse.org/tools/orbit/downloads/drops/R20200831200620/repository/
  3. As most projects use CBI for building, you would simply ensure that the URL is included in the Target Platform configuration

Does Orbit replace or affect the Eclipse Foundation legal process?

NO! Orbit holds only libraries that have been approved by the standard legal process.Projects must still follow this process to request permission to use libraries in their releases.

Do projects have to use the Orbit bundles?

This is not explicitly required however we do hope that the Release Review process is enhanced to require justification for using a library in your release and not using the corresponding bundle from Orbit. There may well be valid scenarios here the Orbit bundle is not appropriate but projects are strongly urged to share as much as possible.

What if I don't want to put the library I need into Orbit?

That's fine but you will be foregoing the help and support you would get of the greater Orbit community as well as preventing others from sharing in your efforts. Keep in mind that you may have to justify this approach when it comes time for your release review.

Who are the committers in Orbit?

See Orbit's Foundation Portal Page for the list of committers.

How do I become a committer in Orbit?

It is possible to contribute libraries to Orbit without being a committer, in the same way one can contribute code to other projects. The contributions are essentially metadata files that generate the library at build time. For repeated maintenance of many different libraries, one can consider applying to become a committer.

Orbit committers are already committers from other Eclipse projects that have a need for a third party library. These people come to Orbit with an approved library and propose to include it in Orbit. If they are not already a committer in Orbit and their project does not have any committers in Orbit, they can become a committer by agreeing to bundle and maintain the new library. Accordingly, they will then be responsible for the care and feeding of that library and the corresponding bundle. You should make your interest known on the Orbit mailing list.

How do you name bundles containing other people's code?

That's a great question! See the documentation and guidelines on Bundle Naming.

Which libraries are managed in Orbit?

The complete list of bundles available in a given Orbit build and links to download them can be seen on the individual Orbit download pages. See also Orbit Bundles.

How does Orbit manage multiple versions of the same library?

Luckily OSGi supports multiple versions of the same bundle installed and running at the same time so this does not present any particular runtime problems. At development time however there is a challenge of project naming. Since the Eclipse convention has been to use the bundle symbolic name as the name of the project, there would be a conflict if two versions of the same project need to be in the workspace at the same time.

How do I add something to Orbit?

There are a number of factors and processes to be considered when adding a library to Orbit. Please see Adding Bundles to Orbit.

How is source managed/delivered?

We generally package source bundles for usage while debugging or while reading the code or JavaDoc. For more information, see Create a Source Bundle.

Do I raise a CQ against Orbit to contribute my 3rd-party lib?

First, you need to raise the CQ against your project in which you intend to use the 3rd-party software, so that your PMC can approve its use in that context. Orbit can file the initial CQ in cases where the project cannot do so.

See Adding Bundles to Orbit for more details.

How do I tell if my change had unintended consequences?

Sometime a change may need to be made to the build infrastructure, such as upgrading a maven plug-in version. (For example this pom.xml change for Bug 572370) When this happens it can be hard to tell if there are unintended consequences. Here are some steps that may be useful to compare entire repositories: (I wrote this steps after running them, it may be that there are some small mistakes, please feel free to update the steps):

  • Clone the orbit repo into two directories so that we can compare before and after the change.
  • In one of the repos, apply the change.
  • Run mvn clean verify in both repos. This will build all the individual bundles, but won't publish them to the ~/.m2/repository. The individual p2 repos will be in each bundle in the the target/repository directory.
  • Unpack all the built jars so they can be diffed (in both repos), for example with find $PWD -path '*target/repository/plugins*' -name '*\.jar' -print -exec sh -c 'mkdir -p $0-d ; cd $0-d ; jar xf $0' {} \; which will create a -d directory for each jar next to the jar with said jar unpacked.
  • Compare the -d directories from the before and after directories find . -path '*target/*plugins*/*-d' -name '*-d' | while read i; do diff --ignore-matching-lines '^#Sun Mar 28 1[45]:' --ignore-matching-lines 'Bnd-LastModified: 16169' -r $i ../orbit-recipes2/$i; done There are many files with timestamps, those lines can be ignored with --ignore-matching-lines with the regex updated for the date you have built locally.

The above diff command will produce the following output for the example listed, showing that only the intended change happened:

$ find . -path '*target/*plugins*/*-d' -name '*-d' | while read i; do diff --ignore-matching-lines '^#Sun Mar 28 1[45]:' --ignore-matching-lines 'Bnd-LastModified: 16169' -r $i ../orbit-recipes2/$i; done
Only in ../orbit-recipes2/./jna/com.sun.jna_5.6.0/target/repository/plugins/com.sun.jna_5.6.0.v20200716-0148.jar-d/com/sun/jna: linux-x86-64
Only in ./jna/com.sun.jna_5.6.0/target/repository/plugins/com.sun.jna_5.6.0.v20200716-0148.jar-d: libjnidispatch.so
'''

Back to the top