Document the usage patterns of `Locations`

[shroffk]

Based on the comment

#3810 (comment)

[kasemir]

Purpose of Locations

The "install" location is where we find the phoebus.sh start script, lib/ and doc/ folders, site_splash.png, site_welcome.html, built-in settings.ini. Used to show the customizable splash screen, welcome page, to bundle site-wide defaults into a site-specific product. Also used by the optional self-update mechanism.

By default it's determined from the location of the Locations class file, extracting /path/to/install from /path/to/install/lib/framework.jar.

The "user" location is where the mementos for saved layouts are kept as well as security info (FileBasedStore).
Defaults to $(user.home)/.phoebus, using the Java system property "user.home".

[shroffk]

@XavSPM can you help expand with the usecases/workflows you enable.

[kasemir]

Requirements for SNS/ORNL

Defaults need to stay as they are for usage out-of-the-box. This supports our self-update, bundling of site-wide settings, and each user has their mementos in $(user.home)/.phoebus.

For beamlines, we have a custom launcher script that updates the "user" location from $(user.home)/.phoebus to some folder on a file server, mostly because in that scenario we like to stay out of the user's home folder. To accomplish that, we need a way to update the user location in our launcher, currently done via

java -Dphoebus.user=/that/folder ....

So install location is always at default, user location is defaulted or set via java property.
We have no need to modify install or user location via preferences, so for me that could be simplified.

[XavSPM]

Hello @shroffk,

Our use of phoebus.user consists of creating customized applications via jpackage:

https://github.com/ControlSystemStudio/phoebus/wiki/Packaging

We design custom applications by modifying the phoebus-product/pom.xml file before compilation, in order to remove modules that are unnecessary for the end user. For example, for a simple visualization tool, the e-log module is not required.

We thus generate mini-applications featuring their own icons, customized configuration files, and dedicated interfaces. To avoid any configuration conflicts between these applications, we assign them distinct names and modify the execution parameter as follows: java -Dphoebus.user=$(user.home)/.app1.

This allows us to have multiple applications on the same workstation, all based on a Phoebus core, but with specific configurations. This simplifies the onboarding process for users who are not accustomed to Phoebus.

Ultimately, my goal is to create a small Python script to facilitate the creation of this type of application. However, I do not have much time to dedicate to this at the moment.

Here is an example of the script I use to generate the package.
build.sh

[georgweiss]

@XavSPM, did you verify that $(user.home) is evaluated when running the installed app rather than during build time? In my jpackage script I'm using:

--java-options -Duser.dir=`echo $HOME`