From Eclipsepedia

Jump to: navigation, search


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 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/
  3. Create a new Target Definition file, and add an Update Site location using the drop's update site URL.
  4. Make sure "Group by Category" is checked.

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.

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?

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?

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.

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?

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 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 Create a Source Bundle.

How do I work with a bundle in Orbit?

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!

  1. Create a repository connection to the orbit repository (CVS URL is :pserver:anonymous@dev.eclipse.org/cvsroot/tools).
  2. Navigate to HEAD/org.eclipse.orbit/<your_project> .
  3. Check your project out into your workspace.
  4. Note that the project will be empty. (this is ok)
  5. 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?

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:

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

See Adding Bundles to Orbit for more details.