Skip to content

https://github.com/eclipse-pde/eclipse.pde/pull/2285 #2286

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merks merged 1 commit into from
Apr 8, 2026
Merged

https://github.com/eclipse-pde/eclipse.pde/pull/2285 #2286

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 37 additions & 21 deletions docs/SourceReferences.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,53 @@
# PDE/UI/SourceReferences

## Contents

* [1 Eclipse Source Reference Headers](#eclipse-source-reference-headers)
* [2 Importing Projects from Git](#importing-projects-from-git)
* [3 Extensibility: Generating and Importing Source Reference Headers](#extensibility-generating-and-importing-source-reference-headers)
* [3.1 Generating Source Reference Headers with Tycho](#generating-source-reference-headers-with-tycho)

## Eclipse Source Reference Headers

PDE supports **Eclipse-SourceReferences** headers to bundle manifests. The header provides a list of [SCMURLs](http://maven.apache.org/scm/scm-url-format.html) that reference the source code associated with a binary bundle. PDE build has extensible support for generating source reference headers and the IDE supports importing projects into the workspace corresponding to headers. Usually a bundle has only one SCMURL associated with it. For example, following is a header included in the "org.eclipse.debug.ui" bundle from the Eclipse 4.19 release:
PDE supports **Eclipse-SourceReferences** headers to bundle manifests.
The header provides a list of [SCM URLs](http://maven.apache.org/scm/scm-url-format.html) that reference the source code associated with a binary bundle.
PDE build has extensible support for generating source reference headers and the IDE supports importing projects into the workspace corresponding to headers.
Usually a bundle has only one SCM URL associated with it.
For example, following is a header included in the `org.eclipse.debug.ui` bundle from the Eclipse 4.19 release:

```text
Eclipse-SourceReferences: scm:git:git://git.eclipse.org/gitroot/platform/eclipse.platform.debug.git;path="org.eclipse.debug.ui";tag="I20210222-1800";commitId=c239e1061cd3e02c6e3cb7f34b2be0be7fea7355
```

Support to generate headers and import from different repositories is extensible. The Eclipse SDK provides support for Git via the eGit project.
Support to generate headers and import from different repositories is extensible.
The Eclipse SDK provides support for Git via the eGit project.

## Importing Projects from Git

The SCMURLs generated in the Eclipse SDK refer to projects in the Eclipse GIT repository. To import projects from GIT use PDE's import wizard (use the **File > Import** action and select **Plug-in Development > Plug-ins and Fragments** on the first page of the import wizard). For this example, we'll import from the active target platform. Choose the **Projects from a repository** radio button at the bottom of the wizard page and press **Next**.
The SCM URLs generated in the Eclipse SDK refer to projects in the Eclipse GIT repository.
To import projects from GIT use PDE's import wizard (use the **File > Import** action and select **Plug-in Development > Plug-ins and Fragments** on the first page of the import wizard).
For this example, we'll import from the active target platform.
Choose the **Projects from a repository** radio button at the bottom of the wizard page and press **Next**.

![Repo-import-1.png](https://raw.githubusercontent.com/eclipse-pde/eclipse.pde/master/docs/images/Repo-import-1.png)
![Repo-import-1.png](images/Repo-import-1.png)
Copy link
Copy Markdown
Contributor Author

@merks merks Apr 8, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vogella

This is was @laeubi was suggesting. Reference to an image in the same repository is best done by a relative URI because then you can preview before you commit..

I'm not sure if you are aware that you can preview the file in a PR:

Image

So I can confirm that what I'm about to merge will actually render correctly.

Image

I think relative URIs only work within a single repository.


All bundles with published SCMURLs will be available for importing. Select the bundles you want to import, and press **Next**. For this example, I have selected bundles related to the debug platform.
All bundles with published SCM URLs will be available for importing.
Select the bundles you want to import, and press **Next**.
For this example, I have selected bundles related to the debug platform.

![Repo-import-2.png](https://raw.githubusercontent.com/eclipse-pde/eclipse.pde/master/docs/images/Repo-import-2.png)
![Repo-import-2.png](images/Repo-import-2.png)

The last page of the wizard allows you to import the specific versions of the projects that were used in the build or from latest version. Pressing **Finish** imports the projects into the workspace, connected to the GIt repository.
The last page of the wizard allows you to import the specific versions of the projects that were used in the build or from latest version.
Pressing **Finish** imports the projects into the workspace, connected to the GIt repository.

![Repo-import-3.png](https://raw.githubusercontent.com/eclipse-pde/eclipse.pde/master/docs/images/Repo-import-3.png)
![Repo-import-3.png](images/Repo-import-3.png)

## Extensibility: Generating and Importing Source Reference Headers

PDE build optionally generates source reference headers during a build. This feature is turned on by specifying the following property:
PDE build optionally generates source reference headers during a build.
This feature is turned on by specifying the following property:

```properties
generateSourceReferences = true
```

The headers themselves are generated by **fetch factories**. PDE build uses fetch factories to fetch source code from repositories (there is an **org.eclipse.pde.build.fetchFactories** extension point). Each repository (CVS, etc.), provides a specific implementation of an **IFetchFactory**. To include source reference headers a fetch factory must provide a **KEY_SOURCE_REFERENCES** property when parsing a map file entry, in the implementation of **parseMapFileEntry(String, Properties, Map)**.
The headers themselves are generated by **fetch factories**.
PDE build uses fetch factories to fetch source code from repositories (there is an **org.eclipse.pde.build.fetchFactories** extension point).
Each repository (CVS, etc.), provides a specific implementation of an **IFetchFactory**.
To include source reference headers a fetch factory must provide a **KEY_SOURCE_REFERENCES** property when parsing a map file entry, in the implementation of **parseMapFileEntry(String, Properties, Map)**.

For example, the CVS fetch factory implementation sets a {key, value} pair in the map for each project being fetched, like:

Expand All @@ -49,10 +57,18 @@ For example, the CVS fetch factory implementation sets a {key, value} pair in th

PDE provides two new **experimental / internal** extension points to support import operations in the SDK:

* _org.eclipse.pde.core.bundleImporters_ - A bundle importer is capable of creating a project in the workspace based on specific entries contained in a bundle manifest (implements **org.eclipse.pde.internal.core.importing.provisional.IBundleImporterDelegate**). A bundle importer is provided with the manifest (map of header value pairs) of each bundle. For each bundle that the importer supports, it creates and returns a bundle import description (org.eclipse.pde.internal.core.importing.provisional.BundleImportDescription).
* _org.eclipse.pde.ui.bundleImportPages_ - A bundle import page provides a wizard page used in the Plug-in import wizard to configure settings for bundles to be imported by a bundle importer extension (implements **org.eclipse.pde.internal.ui.provisional.IBundeImportWizardPage**). The page is provided with any bundle import descriptions associated with bundles the user has selected for import. The page can then modify/annotate/further restrict the bundle import descriptions. The resulting importing descriptions are passed to the bundle importer when finish is pressed.

Since the extension points are experimental the interfaces implemented by the extensions are in the internal (non-API) namespace. The SDK provides implementations of all three extensions for CVS. For example, the CVS bundle import page adds information to bundle import descriptions if the user decides to import from HEAD. The eGit projects provides implementations for Git.
* _org.eclipse.pde.core.bundleImporters_ - A bundle importer is capable of creating a project in the workspace based on specific entries contained in a bundle manifest (implements **org.eclipse.pde.internal.core.importing.provisional.IBundleImporterDelegate**).
A bundle importer is provided with the manifest (map of header value pairs) of each bundle.
For each bundle that the importer supports, it creates and returns a bundle import description (org.eclipse.pde.internal.core.importing.provisional.BundleImportDescription).
* _org.eclipse.pde.ui.bundleImportPages_ - A bundle import page provides a wizard page used in the Plug-in import wizard to configure settings for bundles to be imported by a bundle importer extension (implements **org.eclipse.pde.internal.ui.provisional.IBundeImportWizardPage**).
The page is provided with any bundle import descriptions associated with bundles the user has selected for import.
The page can then modify/annotate/further restrict the bundle import descriptions.
The resulting importing descriptions are passed to the bundle importer when finish is pressed.

Since the extension points are experimental the interfaces implemented by the extensions are in the internal (non-API) namespace.
The SDK provides implementations of all three extensions for CVS.
For example, the CVS bundle import page adds information to bundle import descriptions if the user decides to import from HEAD.
The eGit projects provides implementations for Git.

### Generating Source Reference Headers with Tycho

Expand Down
Loading