Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
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
5 changes: 5 additions & 0 deletions .vscode/settings.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"debug.hideSlowPreLaunchWarning": true,
"java.debug.settings.forceBuildBeforeLaunch": false,
"java.debug.settings.onBuildFailureProceed": false
}
18 changes: 9 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ mvn clean verify -f dependencies/pom.xml

## Building with maven

Define the JAVA_HOME environment variable to point to your Java installation directory.
Define the JAVA_HOME environment variable to point to your Java installation directory.
Mac OS users should use something like:
```
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-21.0.11+10/Contents/Home
Expand Down Expand Up @@ -52,7 +52,7 @@ Set the environment variable `LANG` to `en_US.UTF-8`
to execute tests in a specific locale,
or build with `mvn -DskipTests ...` to skip tests.

### Running the phoebus application
### Running the phoebus application

To run the product jar
```
Expand Down Expand Up @@ -253,20 +253,20 @@ Create a sonatype account and update the maven settings.xml file with your sonat
</servers>
```

**Prepare the release**
`mvn release:prepare`
**Prepare the release**
`mvn release:prepare`
In this step will ensure there are no uncommitted changes, ensure the versions number are correct, tag the scm, etc.
A full list of checks is documented [here](https://maven.apache.org/maven-release/maven-release-plugin/usage/prepare-release.html).

**Perform the release**
`mvn -Darguments="-Dskip-executable-jar" -Pdocs,releases release:perform`
**Perform the release**
`mvn -Darguments="-Dskip-executable-jar" -Pdocs,releases release:perform`
Checkout the release tag, build, sign and push the build binaries to sonatype. The `docs` profile is needed in order
to create required javadocs jars.

**Publish**
**Publish**
Open the staging repository in [sonatype](https://s01.oss.sonatype.org/#stagingRepositories) and hit the *publish* button

**Note:**
In order to keep the ant and maven builds in sync, before the prepare:release update the `version` in the
dependencies\ant_settings.xml to match the release version number. After the release is completed the `version` should
In order to keep the ant and maven builds in sync, before the prepare:release update the `version` in the
dependencies\ant_settings.xml to match the release version number. After the release is completed the `version` should
updated to match the next development snapshotData version.
56 changes: 28 additions & 28 deletions phoebus-product/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,66 +18,66 @@ For site-specific examples, see

* https://github.com/shroffk/nsls2-phoebus (actually creates several products for 'beamline' vs. 'accelerator')
* https://github.com/kasemir/phoebus-sns

## Building native installers with `jpackage`
`jpackage` (https://docs.oracle.com/en/java/javase/14/docs/specs/man/jpackage.html) is a tool bundled with the
JDK from version 14. It can be used to build native installers for MacOS (pkg or dmg),
Windows (msi or exe) and Linux (deb or rpm). Such installers will include all dependencies, including the Java

`jpackage` (https://docs.oracle.com/en/java/javase/14/docs/specs/man/jpackage.html) is a tool bundled with the
JDK from version 14. It can be used to build native installers for MacOS (pkg or dmg),
Windows (msi or exe) and Linux (deb or rpm). Such installers will include all dependencies, including the Java
runtime.

The following use cases have been verified:

* MacOS versions 10,11,12,13, dmg and pkg.
* Windows 10, msi only.

#### Prerequisites

* A working Phoebus build environment, i.e. JDK 11 and Maven.
* `jpackage` must be run on the same OS as the target OS, i.e. cross builds are not supported.
* JDK 14 or newer.
* JDK 14 or newer.
* On Windows you also need to install the "WiX" tools, available here: https://wixtoolset.org/.
* Prepare application icons, to be placed in the top level folder of your product package:
* `ico` for Windows
* `icns` for MacOS
* `png` for Linux

#### Step-by-step

1. Build your product package (zip or gz), e.g. `mvn -Djavafx.platform=[linux|win|mac] clean verify`.
2. Copy the generated zip/gz file to some temporary folder and cd to it.
3. Extract the zip/gz. In the following the folder created is referred to as `unzipped`.
4. Identify the name of the product jar. In the following referred to as `product-<version>-<os>.jar`.
5. Determine a version for your application, in the following referred to as `app_version`.
6. For Window installers determine a menu group in which the application will be placed. If the group does not
exist, it will be created.
exist, it will be created.
7. Identify the path to the Java 11 SDK. In the following referred to as `<jdk_root>`. See below for additional
information on the selecttion of target Java runtime.

##### `jpackage` build step 1
`jpackage --name <app_name> --input unzipped --type app-image --main-jar product-<version>-<os>.jar
--icon unzipped/<OS specific icon file> [--java-options -Dprism.lcdtext=false] --java-options --java-options
-Dcom.sun.webkit.useHTTP2Loader=false --runtime-image <jdk_root>`

NOTE: the `--java-options -Dprism.lcdtext=false` portion is for MacOS only.

Additional Java options are added using `--java-options <my option>`.

##### `jpackage` build step 2, MacOS
`jpackage --name <app_name> --app-version <app_version> --app-image <app_name>.app --type [pkg|dmg]`

##### `jpackage` build step 2, Windows
`jpackage --name <app_name> --app-version <app_version> --app-image <app_name> --type [msi|exe] --win-menu --win-shortcut --win-menu-group <menu_group>`

##### `jpackage` build step 2, Linux
`jpackage --name <app_name> --app-version <app_version> --app-image <app_name> --type [deb|rpm]`
#### Additional installer options
Additional customization of the installer is available for all platforms,

#### Additional installer options
Additional customization of the installer is available for all platforms,
see https://docs.oracle.com/en/java/javase/14/docs/specs/man/jpackage.html.

### Deployment considerations
The application policy of the target OS may prohibit installation or launch of a package or application downloaded over HTTP(S). On
The application policy of the target OS may prohibit installation or launch of a package or application downloaded over HTTP(S). On
Windows 10 the user will be presented with a warning message that can be dismissed to complete the installation. On
MacOS 10.15.7 the installation will complete, but the application may not be able to launch.

Expand All @@ -92,17 +92,17 @@ and MacOS at the European Spallation Source.
### Selection of target Java runtime
During build (step 1) a target Java runtime is specified. If this option (`--runtime-image`) is omitted, `jpackage` will
bundle the Java runtime containing the `jpackage` tool, i.e. Java 14+. Tests on Windows shows that the
target runtime selection may impact the end result, i.e. the Phoebus application installed from the msi file.
For instance, while the Java runtime Adopt JDK 11.0.9 can be bundled into a working installation,
target runtime selection may impact the end result, i.e. the Phoebus application installed from the msi file.
For instance, while the Java runtime Adopt JDK 11.0.9 can be bundled into a working installation,
Adopt JDK 11.0.12 will not work when Phoebus is launched. On MacOS Adopt JDK 11.0.12 works fine.

### Application signing
Starting from MacOS 13.2 (possibly from 13.0), installer packages must be signed for a hassle-free installation process.
To include signing in the `jpackage` build, add the following in step 1:
`--mac-sign
--mac-package-identifier org.phoebus.product.Launcher
--mac-package-name CSS-Phoebus
--mac-signing-keychain "/Library/Keychains/System.keychain"
`--mac-sign
--mac-package-identifier org.phoebus.product.Launcher
--mac-package-name CSS-Phoebus
--mac-signing-keychain "/Library/Keychains/System.keychain"
--mac-signing-key-user-name 'Developer ID Application: European Spallation Source Eric (W2AG9MPZ43)'`.

Here the `--mac-signing-key-user-name` value identifies a certificate installed on the Mac OS host. Note that the
Expand All @@ -111,5 +111,5 @@ Developer Program may request/create such certificates.


`


Loading