Skip to content

Commit 6ba90fb

Browse files
CopilotCopilot
committed
Add documentation for including JRE with Eclipse products (#5601)
Add comprehensive documentation for including JRE with products (cherry picked from commit 0fd7323)
1 parent 3b36c4d commit 6ba90fb

File tree

4 files changed

+398
-0
lines changed

4 files changed

+398
-0
lines changed

‎src/site/markdown/IncludeJRE.md‎

Lines changed: 393 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,393 @@
1+
# Including a JRE with Eclipse Products
2+
3+
When building Eclipse RCP applications, you often want to bundle a Java Runtime Environment (JRE) with your product. This ensures that end users don't need to have Java pre-installed on their systems and guarantees your application runs with a tested, compatible JRE version.
4+
5+
Tycho offers multiple approaches for including a JRE with your product, each with its own advantages and use cases.
6+
7+
## Overview of Available Methods
8+
9+
There are two main approaches to include a JRE with your Eclipse product:
10+
11+
1. **Automatic JRE Inclusion** - Using the `includeJRE="true"` flag in your product file (recommended for most use cases)
12+
2. **Manual JRE Inclusion** - Including JRE features explicitly in your product definition
13+
14+
## Method 1: Automatic JRE Inclusion (Recommended)
15+
16+
The automatic approach uses the `includeJRE="true"` attribute in your `.product` file. When this flag is set, Tycho automatically handles JRE resolution and inclusion during the build process.
17+
18+
### How It Works
19+
20+
When `includeJRE="true"` is set in your product file:
21+
22+
1. It automatically resolves the appropriate JRE based on the product's target environments
23+
2. The JRE is included in the final product materialization and archives
24+
25+
This approach leverages the p2 dependency resolution mechanism, making it the most integrated and streamlined solution.
26+
27+
### Prerequisites
28+
29+
To use automatic JRE inclusion, you only need:
30+
31+
1. Set `includeJRE="true"` in your product file
32+
33+
That's it! Tycho automatically fetches the JRE from the default [JustJ](https://www.eclipse.org/justj/) repository.
34+
35+
### Configuration Example
36+
37+
**Step 1: Set `includeJRE="true"` in your product file**
38+
39+
```xml
40+
<?xml version="1.0" encoding="UTF-8"?>
41+
<?pde version="3.5"?>
42+
43+
<product name="My Application"
44+
uid="my.application.product"
45+
id="my.application.product"
46+
application="org.eclipse.ui.ide.workbench"
47+
version="1.0.0"
48+
type="features"
49+
includeLaunchers="true"
50+
includeJRE="true">
51+
52+
<!-- Your product configuration -->
53+
<features>
54+
<feature id="org.eclipse.platform" installMode="root"/>
55+
<!-- Your other features -->
56+
</features>
57+
58+
</product>
59+
```
60+
61+
That's all you need! When `includeJRE="true"` is set, Tycho automatically:
62+
- Fetches the appropriate JRE from the JustJ repository (https://download.eclipse.org/justj/jres)
63+
- Resolves the correct JRE version based on your product's target environments
64+
- Includes the JRE in the final product
65+
66+
### Customizing the JRE Repository (Optional)
67+
68+
By default, Tycho uses the JustJ repository at `https://download.eclipse.org/justj/jres`. If you need to use a different JRE source or disable automatic JRE fetching, you can configure the `productRepository` parameter in the `tycho-p2-director-plugin`:
69+
70+
```xml
71+
<plugin>
72+
<groupId>org.eclipse.tycho</groupId>
73+
<artifactId>tycho-p2-director-plugin</artifactId>
74+
<version>${tycho-version}</version>
75+
<configuration>
76+
<!-- Use a specific JustJ version repository -->
77+
<productRepository>https://download.eclipse.org/justj/jres/21/updates/release/</productRepository>
78+
79+
<!-- Or disable automatic JRE fetching entirely -->
80+
<!-- <productRepository></productRepository> -->
81+
</configuration>
82+
</plugin>
83+
```
84+
85+
### Choosing a JustJ JRE Version
86+
87+
By default, Tycho uses the base JustJ repository (`https://download.eclipse.org/justj/jres`) which provides JREs for multiple Java versions. If you need a specific Java version, you can configure the `productRepository` parameter as shown above.
88+
89+
Common JustJ repository options:
90+
- Default (all versions): `https://download.eclipse.org/justj/jres`
91+
- Java 17 specific: `https://download.eclipse.org/justj/jres/17/updates/release/`
92+
- Java 21 specific: `https://download.eclipse.org/justj/jres/21/updates/release/`
93+
94+
## Method 2: Manual JRE Inclusion via Features
95+
96+
The manual approach explicitly includes JRE-providing features in your product definition. This gives you more direct control over which JRE components are included.
97+
98+
### Configuration Example
99+
100+
**Step 1: Include JRE feature in your product file**
101+
102+
```xml
103+
<?xml version="1.0" encoding="UTF-8"?>
104+
<?pde version="3.5"?>
105+
106+
<product name="My Application"
107+
uid="my.application.product"
108+
version="1.0.0"
109+
type="features"
110+
includeLaunchers="true">
111+
112+
<features>
113+
<!-- Include JustJ JRE feature explicitly -->
114+
<feature id="org.eclipse.justj.openjdk.hotspot.jre.full"/>
115+
116+
<!-- Your application features -->
117+
<feature id="org.eclipse.platform" installMode="root"/>
118+
<!-- Your other features -->
119+
</features>
120+
121+
</product>
122+
```
123+
124+
**Step 2: Add JustJ repository to your pom.xml**
125+
126+
```xml
127+
<repositories>
128+
<repository>
129+
<id>justj</id>
130+
<url>https://download.eclipse.org/justj/jres/21/updates/release/</url>
131+
<layout>p2</layout>
132+
</repository>
133+
</repositories>
134+
```
135+
136+
**Step 3: Configure target platform**
137+
138+
```xml
139+
<plugin>
140+
<groupId>org.eclipse.tycho</groupId>
141+
<artifactId>target-platform-configuration</artifactId>
142+
<version>${tycho-version}</version>
143+
<configuration>
144+
<executionEnvironment>none</executionEnvironment>
145+
</configuration>
146+
</plugin>
147+
```
148+
149+
### When to Use Manual Inclusion
150+
151+
The manual approach is useful when:
152+
153+
- You want explicit control over which JRE feature variant is included
154+
- You're migrating from an older product configuration
155+
- You need to include additional JRE-related features or fragments
156+
157+
## Comparison of Methods
158+
159+
| Aspect | Automatic (`includeJRE="true"`) | Manual (Feature-based) |
160+
|--------|--------------------------------|------------------------|
161+
| **Simplicity** | Simple, minimal configuration | Requires explicit feature listing |
162+
| **Flexibility** | Automatic resolution | Full control over JRE selection |
163+
| **Maintenance** | Lower maintenance | Manual feature updates needed |
164+
| **Recommended for** | Most new projects | Projects needing fine-grained control |
165+
166+
## Verifying JRE Inclusion
167+
168+
After building your product, verify that the JRE was included correctly:
169+
170+
1. **Check the build output**: Look for messages indicating JRE resolution
171+
2. **Inspect the materialized product**: Navigate to `target/products/[product-id]/[os]/[ws]/[arch]/` and verify the JRE directory exists
172+
3. **Test the product**: Launch the product and verify it runs without requiring a system-installed Java
173+
174+
The JRE is typically placed in a `jre` or `jdk` subdirectory within your product's root directory.
175+
176+
## Troubleshooting
177+
178+
### JRE Not Found During Build
179+
180+
**Problem**: Tycho cannot resolve the JRE during product materialization when using automatic inclusion.
181+
182+
**Solutions**:
183+
- Ensure the `includeJRE="true"` attribute is present in your product file
184+
- Check that the `productRepository` parameter is configured correctly (if customized)
185+
- Verify internet connectivity to download from the JustJ repository
186+
187+
**Problem**: Tycho cannot resolve the JRE when using manual feature inclusion.
188+
189+
**Solutions**:
190+
- Verify that your JustJ repository URL is correct and accessible in the `<repositories>` section
191+
- Check that `executionEnvironment` is set to `none` in target-platform-configuration to avoid conflicts
192+
193+
### Multiple JRE Versions Resolved
194+
195+
**Problem**: Multiple JRE versions are being resolved, causing conflicts.
196+
197+
**Solutions**:
198+
- When using automatic inclusion: Configure a specific JRE version via the `productRepository` parameter
199+
- When using manual inclusion: Specify only one JustJ repository in your `<repositories>` section
200+
- Review your target platform configuration to ensure no conflicting JRE sources
201+
202+
### Product Fails to Launch
203+
204+
**Problem**: The product builds successfully but fails to launch on the target system.
205+
206+
**Solutions**:
207+
- Verify the JRE architecture (x86_64, aarch64) matches your product's target environment
208+
- Check that the product's launcher is correctly configured to use the bundled JRE
209+
- Ensure the JRE version is compatible with your Eclipse platform and plugins
210+
211+
### Understanding `executionEnvironment=none` (Manual Method Only)
212+
213+
**Why is this needed for manual JRE inclusion?**
214+
215+
When manually including JRE features in your product, you need to set `executionEnvironment=none` in the target-platform-configuration.
216+
217+
By default, Tycho injects mock "a.jre" units into the target platform to satisfy Java package imports (like `javax.xml`, `java.util`, etc.) and execution environment requirements. These mock units don't provide an actual JRE—they're just markers for dependency resolution.
218+
219+
When you explicitly add JustJ features to your target platform, which provides real JRE bundles with the same capabilities, you get conflicts. Setting `executionEnvironment=none` tells Tycho: "Don't inject your mock JRE units; I'm providing a real JRE through my target platform."
220+
221+
**Note**: This is NOT needed for automatic JRE inclusion with `includeJRE="true"`, as Tycho handles the JRE outside of the target platform.
222+
223+
## Complete Working Example
224+
225+
Here's a complete, minimal example for a product with automatic JRE inclusion:
226+
227+
**my-product.product:**
228+
```xml
229+
<?xml version="1.0" encoding="UTF-8"?>
230+
<?pde version="3.5"?>
231+
232+
<product name="My RCP Application"
233+
uid="com.example.myapp"
234+
id="com.example.myapp.product"
235+
application="org.eclipse.ui.ide.workbench"
236+
version="1.0.0.qualifier"
237+
type="features"
238+
includeLaunchers="true"
239+
includeJRE="true"
240+
autoIncludeRequirements="true">
241+
242+
<configIni use="default"/>
243+
244+
<launcherArgs>
245+
<vmArgsMac>-XstartOnFirstThread</vmArgsMac>
246+
</launcherArgs>
247+
248+
<launcher name="myapp">
249+
<win useIco="false">
250+
<bmp/>
251+
</win>
252+
</launcher>
253+
254+
<features>
255+
<feature id="org.eclipse.platform" installMode="root"/>
256+
<!-- Add your application features here -->
257+
</features>
258+
259+
<configurations>
260+
<plugin id="org.apache.felix.scr" autoStart="true" startLevel="2" />
261+
<plugin id="org.eclipse.core.runtime" autoStart="true" startLevel="0" />
262+
<plugin id="org.eclipse.equinox.common" autoStart="true" startLevel="2" />
263+
</configurations>
264+
265+
</product>
266+
```
267+
268+
**pom.xml:**
269+
```xml
270+
<?xml version="1.0" encoding="UTF-8"?>
271+
<project xmlns="http://maven.apache.org/POM/4.0.0"
272+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
273+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
274+
https://maven.apache.org/maven-v4_0_0.xsd">
275+
<modelVersion>4.0.0</modelVersion>
276+
277+
<groupId>com.example</groupId>
278+
<artifactId>com.example.myapp.product</artifactId>
279+
<version>1.0.0-SNAPSHOT</version>
280+
<packaging>eclipse-repository</packaging>
281+
282+
<properties>
283+
<tycho-version>5.0.0</tycho-version>
284+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
285+
</properties>
286+
287+
<repositories>
288+
<repository>
289+
<id>eclipse-2024-12</id>
290+
<url>https://download.eclipse.org/releases/2024-12/</url>
291+
<layout>p2</layout>
292+
</repository>
293+
</repositories>
294+
295+
<build>
296+
<plugins>
297+
<plugin>
298+
<groupId>org.eclipse.tycho</groupId>
299+
<artifactId>tycho-maven-plugin</artifactId>
300+
<version>${tycho-version}</version>
301+
<extensions>true</extensions>
302+
</plugin>
303+
304+
<plugin>
305+
<groupId>org.eclipse.tycho</groupId>
306+
<artifactId>tycho-p2-director-plugin</artifactId>
307+
<version>${tycho-version}</version>
308+
<executions>
309+
<execution>
310+
<id>materialize-products</id>
311+
<goals>
312+
<goal>materialize-products</goal>
313+
</goals>
314+
</execution>
315+
<execution>
316+
<id>archive-products</id>
317+
<goals>
318+
<goal>archive-products</goal>
319+
</goals>
320+
</execution>
321+
</executions>
322+
</plugin>
323+
</plugins>
324+
</build>
325+
</project>
326+
```
327+
328+
Build the product:
329+
```bash
330+
mvn clean verify
331+
```
332+
333+
The resulting product archives will be in `target/products/` with the JRE included.
334+
335+
## Additional Resources
336+
337+
- [JustJ Project](https://www.eclipse.org/justj/) - Pre-packaged JRE distributions for Eclipse
338+
- [Building Products](Products.html) - General information about building Eclipse products
339+
- [Tycho P2 Director Plugin](tycho-p2-director-plugin/plugin-info.html) - Plugin for materializing products
340+
- [Demo Projects](https://github.com/eclipse-tycho/tycho/tree/master/demo/justj) - Working examples of JRE inclusion
341+
- `automaticInstall` - Example using `includeJRE="true"`
342+
- `product` - Example using manual feature inclusion
343+
344+
## Common Questions
345+
346+
### Can I use a different JRE provider instead of JustJ?
347+
348+
Yes, you can use any JRE provider that publishes JRE artifacts as p2 installable units. The key requirement is that the JRE provider must supply p2 IUs with the appropriate capabilities.
349+
350+
### Does `includeJRE="true"` work with all operating systems?
351+
352+
Yes, Tycho automatically resolves the appropriate JRE for each target environment. JustJ provides JRE distributions for Windows, macOS, and Linux on various architectures (x86_64, aarch64).
353+
354+
### What's the difference between `jre.full` and other JRE features?
355+
356+
This question applies to the manual JRE inclusion method. JustJ provides different JRE feature variants:
357+
- `org.eclipse.justj.openjdk.hotspot.jre.full` - Complete JRE with all modules
358+
- `org.eclipse.justj.openjdk.hotspot.jre.minimal` - Minimal JRE for reduced size
359+
360+
Choose based on your application's Java module requirements. Most applications should use the `full` variant unless you have specific size constraints and know your exact module dependencies.
361+
362+
### How do I include JREs for multiple platforms?
363+
364+
Tycho automatically handles multi-platform builds. Simply define multiple target environments in your target-platform-configuration:
365+
366+
```xml
367+
<plugin>
368+
<groupId>org.eclipse.tycho</groupId>
369+
<artifactId>target-platform-configuration</artifactId>
370+
<version>${tycho-version}</version>
371+
<configuration>
372+
<environments>
373+
<environment>
374+
<os>win32</os>
375+
<ws>win32</ws>
376+
<arch>x86_64</arch>
377+
</environment>
378+
<environment>
379+
<os>linux</os>
380+
<ws>gtk</ws>
381+
<arch>x86_64</arch>
382+
</environment>
383+
<environment>
384+
<os>macosx</os>
385+
<ws>cocoa</ws>
386+
<arch>x86_64</arch>
387+
</environment>
388+
</environments>
389+
</configuration>
390+
</plugin>
391+
```
392+
393+
Tycho will automatically resolve and include the appropriate JRE for each platform when `includeJRE="true"` is set.

‎src/site/markdown/Products.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -212,4 +212,5 @@ Activate the profile with: `mvn clean verify -Pdevelopment`
212212
- [Tycho P2 Director Plugin Documentation](tycho-p2-director-plugin/plugin-info.html) - Complete reference for all configuration options
213213
- [Tycho P2 Repository Plugin Documentation](tycho-p2-repository-plugin/plugin-info.html) - For configuring the P2 repository
214214
- [Packaging Types](PackagingTypes.html) - Information about the `eclipse-repository` packaging type
215+
- [Including a JRE with Products](IncludeJRE.html) - How to bundle a Java Runtime Environment with your product
215216
- [Signing Products](SignProducts.html) - How to sign custom Eclipse products with Tycho

0 commit comments

Comments
 (0)