From 60260cb4cb4414b93296b4098ab8b560a2a14197 Mon Sep 17 00:00:00 2001 From: Oliver Sanders Date: Fri, 19 Apr 2024 13:00:43 +0100 Subject: [PATCH 1/2] add developer docs --- DEVELOPING.md | 67 ++++ README.md | 4 + etc/cylc-rose-opts.svg | 782 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 853 insertions(+) create mode 100644 DEVELOPING.md create mode 100644 etc/cylc-rose-opts.svg diff --git a/DEVELOPING.md b/DEVELOPING.md new file mode 100644 index 00000000..7ac54fd5 --- /dev/null +++ b/DEVELOPING.md @@ -0,0 +1,67 @@ +# Cylc Rose Dev Docs + +Cylc Rose provides integration between Cylc and Rose. + +Its functionality is defined in the +[cylc-rose proposal](https://github.com/cylc/cylc-admin/blob/master/docs/proposal-cylc-rose-installing-rose-configs.md). + +## Cylc Rose Options + +### Rose Config Files + +Rose suite configurations are Cylc workflows which contain a `rose-suite.conf` +file at the top level. This file configures: + +* Template variables. +* File installation. +* Environment variables for workflow configuration. + +Rose suite configurations may additionally contain optional configuration files +in the `opts/` directory. Note that optional configurations may be turned on by +default via the `opt` configuration in the `rose-suite.conf` file. + +### The Options + +The Rose suite configuration may be extended or overridden via the Cylc Rose +CLI options. + +Cylc Rose adds three options to Cylc Flow. + +* `-S` - template variables +* `-D` - any arbitrary rose configuration (includes template variables) +* `-O` - optional configs + +These options are currently hardcoded in the cylc-flow source code as we +do not yet have the ability for Cylc plugins (such as cylc-rose) to inject +options into cylc-flow commands. + +There is also the `ROSE_SUITE_OPT_CONF_KEYS` environment variable which compliments +the `-O` option. + +### Storage + +Cylc Rose options passed in on the CLI are written to the +`~/cylc-run//opt/rose-suite-cylc-install.conf` file by +the `post_install` plugin. + +This preserves these options so that they are inherited by subsequent commands +avoiding the need for users to remember which Cylc Rose options they have used +and specify them with all future commands. + +### Reinstallation + +On reinstallation, additional Cylc Rose CLI options may be provided. + +If specified, these will override those previously specified on the CLI. + +### Option Lifecycle + +In order to support Cylc's compound commands (single commands that may perform +multiple individual operations as a transaction), the `post_install` plugin +deletes the Cylc Rose CLI options (from the object it was passed) after it has +written them to the filesystem. + +This is necessary to avoid the same options being reenacted in later stages of +compound commands. See https://github.com/cylc/cylc-flow/issues/5968 + +![lifecycle-diagram](./etc/cylc-rose-opts.svg) diff --git a/README.md b/README.md index d1d92143..60e3c215 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,10 @@ This plugin provides support for the `rose-suite.conf` file, namely: the new Cylc `symlink dirs` functionality. * Graphical configuration editors. +### How It Works + +For developer documentation, see [DEVELOPING](DEVELOPING.md). + ### Contributing [![Contributors](https://img.shields.io/github/contributors/cylc/cylc-rose.svg?color=9cf)](https://github.com/cylc/cylc-rose/graphs/contributors) diff --git a/etc/cylc-rose-opts.svg b/etc/cylc-rose-opts.svg new file mode 100644 index 00000000..77a4b92f --- /dev/null +++ b/etc/cylc-rose-opts.svg @@ -0,0 +1,782 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Rose Opts + Command + -S & -D & -O + Validate + Install + Play + Validate + Reinstall + Reload + Clean + pre_configure + post_install + + pre_configure + pre_configure + + + + + + + + + + + + pre_configure + pre_configure + post_install + pre_configure + Reload + pre_configure + File System + opts/rose-suite-cylc-install.conf + + + + + + + + + + + + + + + + + + + + + + + + + + + + + vip + + + + vr + reload + UserCommand + + From 0bf524012228258cf720826724d7653b3020e011 Mon Sep 17 00:00:00 2001 From: Oliver Sanders Date: Tue, 23 Apr 2024 15:25:43 +0100 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Ronnie Dutta <61982285+MetRonnie@users.noreply.github.com> --- DEVELOPING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DEVELOPING.md b/DEVELOPING.md index 7ac54fd5..47acbd16 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -35,7 +35,7 @@ These options are currently hardcoded in the cylc-flow source code as we do not yet have the ability for Cylc plugins (such as cylc-rose) to inject options into cylc-flow commands. -There is also the `ROSE_SUITE_OPT_CONF_KEYS` environment variable which compliments +There is also the `ROSE_SUITE_OPT_CONF_KEYS` environment variable which complements the `-O` option. ### Storage