Clarify install target docs. - #929
Conversation
MetRonnie
left a comment
MetRonnie
left a comment
There was a problem hiding this comment.
Thanks, I was unclear on this myself
4f3d4b4 to
68a14d3
Compare
|
@oliver-sanders or @dpmatthews - @MetRonnie has approved this, but can one of you comment on my question above re use of |
Co-authored-by: Ronnie Dutta <61982285+MetRonnie@users.noreply.github.com>
68a14d3 to
1a0e670
Compare
dpmatthews
left a comment
dpmatthews
left a comment
There was a problem hiding this comment.
I now think it's clearer, and more accurate, if we talk about $HOME directories rather than filesystems (for example, you could have platforms which share the same network filesystem but use different $HOME directories on that filesystem).
I also think we need a note in the "Symlinking Directories" section:
Note: If multiple platforms share the same install target and you specify a symlink directory such as ``log = $DATADIR`` then it is essential that ``$DATADIR`` is defined on all the platforms and points to the same filesystem.
| - An ``install target``, representing each distinct filesystem that Cylc might | ||
| need to install workflow files on. |
There was a problem hiding this comment.
Suggestion:
An ``install target``, representing the ``$HOME`` directory used on the platform.
| An install target is an arbitrary label to identify a distinct file system. All | ||
| platforms that see the same filesystem should specify the same install target | ||
| so that Cylc knows where it needs to install workflow files. |
There was a problem hiding this comment.
Suggestion:
An install target is an arbitrary label to identify the $HOME directory. All platforms that share the same $HOME directories should specify the same install target so that Cylc knows whether it needs to install workflow files.
There was a problem hiding this comment.
or maybe:
An install target is an arbitrary label to identify the distinct filesystem used to store the $HOME directories. All platforms that share the same $HOME directories (i.e. the same files) should specify the same install target so that Cylc knows whether it needs to install workflow files
| Note, if missing from the configuration, the install target will default to | ||
| the platform name. If incorrectly configured, this will cause errors in | ||
| :ref:`RemoteInit` due to Cylc finding files there already during setup. |
There was a problem hiding this comment.
Suggestion:
Note, if missing from the configuration, the install target will default to the platform name (which is fine if there are no other platforms using the same $HOME directories). However, if incorrectly configured (i.e. you use platforms which share $HOME directories but use different install targets), this will cause errors in :ref:RemoteInit due to Cylc finding files there already during setup.
In the examples I've looked at, |
@dpmatthews OK I hadn't thought of that. Do you know of actual cases of this - different platforms with different home paths on the same filesystem?? Anyhow, "talking about $HOME directories rather than filesystems" could also be confusing. It's common to have the same username and home dir path on different platforms (with separate filesystems) and I'm pretty sure many users would think of that as "having the same home directory" on those platforms. Whereas, they are really "different home directories with the same path". What's the easiest way to explain this clearly? Maybe we need to talk about both filesystems and home directories to avoid any misunderstandings 🤔 |
Yes, we'd have to make the changes self-consistent of course. I just think that our frequent use of |
Possibly once in the past. |
3 participants
Companion of cylc/cylc-flow#7315
Current docs are a bit misleading (IMO) on exactly what an
install targetis.Question: can we also change
install target = localhostin various example to something else, e.g.local_clusterto make it more obvious that an install target is not a hostname?Requirements check-list
CONTRIBUTING.mdand added my name as a Code Contributor.