Skip to content

Commit 254e8df

Browse files
vogellavogella
committed
Additional changes: - Standardized headings to ATX style (#, ##, ###). - Converted indented code blocks and inline code with complex content to triple-backtick fenced code blocks with language hints (xml, properties, text). - Fixed a broken/messy inline link within the Eclipse-SourceReferences example. - Removed unnecessary backslash escaping in XML comments. - Removed the manual Table of Contents as it is synthesized by the website. - Reformatted paragraphs to start each sentence on a new line for easier future editing.
1 parent 1aece37 commit 254e8df

4 files changed

Lines changed: 121 additions & 0 deletions

File tree

‎docs/SourceReferences.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# PDE/UI/SourceReferences
2+
3+
## Eclipse Source Reference Headers
4+
5+
PDE supports **Eclipse-SourceReferences** headers to bundle manifests.
6+
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.
7+
PDE build has extensible support for generating source reference headers and the IDE supports importing projects into the workspace corresponding to headers.
8+
Usually a bundle has only one SCMURL associated with it.
9+
For example, following is a header included in the "org.eclipse.debug.ui" bundle from the Eclipse 4.19 release:
10+
11+
```text
12+
Eclipse-SourceReferences: scm:git:git://git.eclipse.org/gitroot/platform/eclipse.platform.debug.git;path="org.eclipse.debug.ui";tag="I20210222-1800";commitId=c239e1061cd3e02c6e3cb7f34b2be0be7fea7355
13+
```
14+
15+
Support to generate headers and import from different repositories is extensible.
16+
The Eclipse SDK provides support for Git via the eGit project.
17+
18+
## Importing Projects from Git
19+
20+
The SCMURLs generated in the Eclipse SDK refer to projects in the Eclipse GIT repository.
21+
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).
22+
For this example, we'll import from the active target platform.
23+
Choose the **Projects from a repository** radio button at the bottom of the wizard page and press **Next**.
24+
25+
![Repo-import-1.png](https://raw.githubusercontent.com/vogella/oomph/master/docs/images/Repo-import-1.png)
26+
27+
All bundles with published SCMURLs will be available for importing.
28+
Select the bundles you want to import, and press **Next**.
29+
For this example, I have selected bundles related to the debug platform.
30+
31+
![Repo-import-2.png](https://raw.githubusercontent.com/vogella/oomph/master/docs/images/Repo-import-2.png)
32+
33+
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.
34+
Pressing **Finish** imports the projects into the workspace, connected to the GIt repository.
35+
36+
![Repo-import-3.png](https://raw.githubusercontent.com/vogella/oomph/master/docs/images/Repo-import-3.png)
37+
38+
## Extensibility: Generating and Importing Source Reference Headers
39+
40+
PDE build optionally generates source reference headers during a build.
41+
This feature is turned on by specifying the following property:
42+
43+
```properties
44+
generateSourceReferences = true
45+
```
46+
47+
The headers themselves are generated by **fetch factories**.
48+
PDE build uses fetch factories to fetch source code from repositories (there is an **org.eclipse.pde.build.fetchFactories** extension point).
49+
Each repository (CVS, etc.), provides a specific implementation of an **IFetchFactory**.
50+
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)**.
51+
52+
For example, the CVS fetch factory implementation sets a {key, value} pair in the map for each project being fetched, like:
53+
54+
```text
55+
{"sourceReferences", "Eclipse-SourceReferences: scm:cvs:pserver:dev.eclipse.org:/cvsroot/eclipse:org.eclipse.debug.core;tag=v20100427"}
56+
```
57+
58+
PDE provides two new **experimental / internal** extension points to support import operations in the SDK:
59+
60+
* _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**).
61+
A bundle importer is provided with the manifest (map of header value pairs) of each bundle.
62+
For each bundle that the importer supports, it creates and returns a bundle import description (org.eclipse.pde.internal.core.importing.provisional.BundleImportDescription).
63+
* _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**).
64+
The page is provided with any bundle import descriptions associated with bundles the user has selected for import.
65+
The page can then modify/annotate/further restrict the bundle import descriptions.
66+
The resulting importing descriptions are passed to the bundle importer when finish is pressed.
67+
68+
Since the extension points are experimental the interfaces implemented by the extensions are in the internal (non-API) namespace.
69+
The SDK provides implementations of all three extensions for CVS.
70+
For example, the CVS bundle import page adds information to bundle import descriptions if the user decides to import from HEAD.
71+
The eGit projects provides implementations for Git.
72+
73+
### Generating Source Reference Headers with Tycho
74+
75+
Source reference headers can also be generated with Tycho with [tycho-packaging:package-plugin](https://www.eclipse.org/tycho/sitedocs/tycho-packaging-plugin/package-plugin-mojo.html).
76+
77+
For example, if a project is located in Eclipse's Git repos add a property with the SCM URL like this:
78+
79+
```xml
80+
<properties>
81+
<tycho.scmUrl>scm:git:git://git.eclipse.org/gitroot/cdt/org.eclipse.cdt.git</tycho.scmUrl>
82+
</properties>
83+
```
84+
85+
For a repository located on GitHub the equivalent property would look like:
86+
87+
```xml
88+
<properties>
89+
<tycho.scmUrl>scm:git:https://github.com/eclipse/january.git</tycho.scmUrl>
90+
</properties>
91+
```
92+
93+
Then add the packaging plug-in to the build:
94+
95+
```xml
96+
<build>
97+
<plugins>
98+
<plugin>
99+
<groupId>org.eclipse.tycho</groupId>
100+
<artifactId>tycho-packaging-plugin</artifactId>
101+
<version>${tycho-version}</version>
102+
<dependencies>
103+
<!-- Use jgit to resolve source references for git: type SCM -->
104+
<dependency>
105+
<groupId>org.eclipse.tycho.extras</groupId>
106+
<artifactId>tycho-sourceref-jgit</artifactId>
107+
<version>${tycho-extras-version}</version>
108+
</dependency>
109+
</dependencies>
110+
<configuration>
111+
<sourceReferences>
112+
<!-- Generate the source reference in the MANIFEST.MF -->
113+
<generate>true</generate>
114+
</sourceReferences>
115+
</configuration>
116+
</plugin>
117+
</plugins>
118+
</build>

‎docs/images/Repo-import-1.png‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs/images/Repo-import-2.png‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs/images/Repo-import-3.png‎

Lines changed: 1 addition & 0 deletions
Loading

0 commit comments

Comments
 (0)