Packaging

Phoebus Packaging

The phoebus source code includes launch scripts to invoke java with the appropriate options to run the product and support self-update. https://github.com/kasemir/phoebus-sns has examples for bundling a JRE with the product, or for wrapping it in a Mac OS *.app.

Since version 14, the JDK includes jpackage. It packages a Java app with a 'native' launcher, but there are two issues:

• The default output won't include the online doc nor support self-update.
• jpackage must run on the actual target OS, i.e. Linux, Mac OS, Windows.

The packager can run in two passes via the --type app-image option.

The first pass constructs a runnable application. After the first pass, one can add resources like help files and maybe another start script to support online update. The result can be launched.

While one could ZIP the result of the first pass for distribution, a second jpackage pass wraps the runnable application into an installer.

To perform as much as possible on a Linux build host, one could try running the first pass of the tool on each OS once, then strip the generated output to a skeleton, re-use it with the latest build result via custom shell scripts, and ZIP for distribution. But many generated files make this impractical. Using jpackage thus seems unsuited for use on just a Linux build host, but would require separate build hosts for Linux, Windows, Mac OS.

The following describes the basic use of jpackage on different platforms, including online help, but not replacing the launcher with a (wrapper) script that would support self-update.

Mac OS X

Build:

cd phoebus
ant clean
ant

Assemble runnable application:

cd phoebus-product/target
V=`echo product-*.jar | sed 's/product-//' | sed 's/.jar//'`
rm -rf CSS_Phoebus.app

# May get icon from e.g.
# https://github.com/kasemir/phoebus-sns/blob/master/app_template/Contents/Resources/cmd.icns
# and add via --icon /path/to/css.icns
$JAVA_HOME/bin/jpackage --name CSS_Phoebus --input lib --main-jar ../product-$V.jar  --type app-image

Add online help

cp -r ../../docs/build/html CSS_Phoebus.app/Contents
mv CSS_Phoebus.app/Contents/html/ CSS_Phoebus.app/Contents/doc

The application could be used as is:

open CSS_Phoebus.app
CSS_Phoebus.app/Contents/MacOS/CSS_Phoebus -help

It could also be copied to /Applications, or ZIPed for distribution so end-users then unZIP and move to /Applications.

A second jpackage pass wraps it into a *.dmg:

$JAVA_HOME/bin/jpackage --name CSS_Phoebus --app-version $V --app-image CSS_Phoebus.app

The resulting CSS_Phoebus-$V.dmg can be distributed to users who open it, drag the "CSS_Phoebus" into "Applications" and then run it as usual.

Windows

Build:

cd phoebus
ant clean
ant

Assemble runnable application:

cd phoebus-product\target

set V=4.6.3
rmdir CSS_Phoebus /Q/S
%JAVA_HOME%\bin\jpackage --name CSS_Phoebus --input lib --main-jar ..\product-%V%.jar --win-console --type app-image

Add online help

mkdir CSS_Phoebus\doc\
xcopy ..\..\docs\build\html CSS_Phoebus\doc\ /E

The application could be used as is:

CSS_Phoebus\CSS_Phoebus.exe -help
CSS_Phoebus\CSS_Phoebus.exe -resource "pv://?sim://sine&app=probe"

It could also be copied to C:\Program Files, or ZIPed for distribution so end-users then unZIP and move wherever they want.

The second jpackage pass to wrap it into an installer requires the WiX tools. Download wix311-binaries.zip from https://wixtoolset.org, unpack, place on path.

%JAVA_HOME%\bin\jpackage --name CSS_Phoebus --app-version %V% --win-per-user-install --win-menu --win-shortcut --app-image CSS_Phoebus

The resulting CSS_Phoebus-%V%.exe can be distributed to end users who run it to install. The result will be found under C:\\Program Files\CSS_Phoebus.

Linux

Build:

cd phoebus
ant clean
ant

Assemble runnable application:

cd phoebus-product/target
V=`echo product-*.jar | sed 's/product-//' | sed 's/.jar//'`
rm -rf CSS_Phoebus

# May get icon from e.g.
# https://github.com/kasemir/phoebus-sns/blob/master/app_template/Contents/Resources/cmd.icns
# and add via --icon /path/to/css.icns
$JAVA_HOME/bin/jpackage --name CSS_Phoebus --input lib --main-jar ../product-$V.jar  --type app-image

Add online help

cp -r ../../docs/build/html CSS_Phoebus/lib
mv CSS_Phoebus/lib/html CSS_Phoebus/lib/doc

The application could be used as is:

CSS_Phoebus/bin/CSS_Phoebus -help
CSS_Phoebus/bin/CSS_Phoebus -resource "pv://?sim://sine&app=probe"

It could also be ZIPed for distribution.

A second jpackage pass wraps it into a *.rpm:

$JAVA_HOME/bin/jpackage --name CSS_Phoebus --app-version $V --app-image CSS_Phoebus

The resulting css_phoebus-$V-1.x86_64.rpm will install as /opt/css_phoebus.