Orbit/FAQ

Note: The contents of this page are retained for historical significance. Please see https://github.com/eclipse/orbit#readme for current information.

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
'''