Merge pull request #736 from wxtim/feature.CYLC_SHARE_CYCLE_DIR

Updated docs about using ROSE_DATAC

Author: wxtim

src/reference/job-script-vars/var-list.txt

@@ -25,9 +25,9 @@ CYLC_WORKFLOW_RUN_DIR              # Location of the run directory in
 CYLC_WORKFLOW_HOST                 # Host running the workflow process
 CYLC_WORKFLOW_OWNER                # User ID running the workflow process
 
-CYLC_WORKFLOW_SHARE_DIR            # Workflow (or task!) shared directory (see below)
+CYLC_WORKFLOW_SHARE_DIR            # Workflow (or task!) shared directory
 CYLC_WORKFLOW_UUID                 # Workflow UUID string
-CYLC_WORKFLOW_WORK_DIR             # Workflow work directory (see below)
+CYLC_WORKFLOW_WORK_DIR             # Workflow work directory
 
 CYLC_TASK_JOB                      # Job identifier expressed as
                                    # CYCLE-POINT/TASK-NAME/SUBMIT-NUMBER
@@ -54,6 +54,8 @@ CYLC_TASK_LOG_ROOT                 # The job script path
                                    #   e.g. ~/cylc-run/foo/log/job/20110511T1800Z/t1/01/job
 CYLC_TASK_WORK_DIR                 # Location of task work directory (see below)
                                    #   e.g. ~/cylc-run/foo/work/20110511T1800Z/t1
+CYLC_TASK_SHARE_CYCLE_DIR          # The share/cycle/<cycle-point> directory
+                                   # for this task.
 
 CYLC_TASK_NAMESPACE_HIERARCHY      # Linearised family namespace of the task,
                                    #   e.g. root postproc t1

src/workflow-design-guide/general-principles.rst

@@ -451,27 +451,30 @@ Primarily, for self-containment (see :ref:`Self-Contained Workflows`) shared IO
 paths should be under the *workflow share directory*, the location of which is
 passed to all tasks as ``$CYLC_WORKFLOW_SHARE_DIR``.
 
-The ``rose task-env`` utility can provide additional environment
-variables that refer to static and cyclepoint-specific locations under the
-workflow share directory.
+The ``$CYLC_TASK_SHARE_CYCLE_DIR`` variable can be used to target
+cyclepoint-specific locations under the workflow share directory.
 
-.. code-block:: cylc
+Sometimes it may be useful to refer to other cycles - to do this use
+``isodatetime``:
 
-   [runtime]
-       [[my-task]]
-           env-script = $(eval rose task-env -T P1D -T P2D)
+.. code-block:: bash
 
-For a current cycle point of ``20170105`` this will make the following
-variables available to tasks:
+   # Cylc task script
+   CYCLE_POINT_MINUS_P1D=$(isodatetime "${CYLC_TASK_CYCLE_POINT} --offset -P1D)"
+   SHARE_CYCLE_DIR_MINUS_P1D="${CYLC_WORKFLOW_SHARE_DIR}/cycle/${CYCLE_POINT_MINUS_P1D}"
+   mkdir -p "${SHARE_CYCLE_DIR_MINUS_P1D}"
+   echo "I believe in ..." > "${SHARE_CYCLE_DIR_MINUS_P1D}/somefile"
 
-.. code-block:: bash
+See ``isodatetime --help`` for usage instructions.
+
+.. versionadded:: 8.5.0
 
-   ROSE_DATA=$CYLC_WORKFLOW_SHARE_DIR/data
-   ROSE_DATAC=$CYLC_WORKFLOW_SHARE_DIR/cycle/20170105
-   ROSE_DATACP1D=$CYLC_WORKFLOW_SHARE_DIR/cycle/20170104
-   ROSE_DATACP2D=$CYLC_WORKFLOW_SHARE_DIR/cycle/20170103
+   ``$CYLC_TASK_SHARE_CYCLE_DIR`` (used in combination with the ``isodatetime``
+   command) is designed to
+   provide a Cylc internal replacement for the use of ``rose task-env``
+   to provide ``$ROSE_DATAC`` and derived variables.
 
-Subdirectories of ``$ROSE_DATAC`` etc. should be agreed between
+Subdirectories of ``$CYLC_TASK_SHARE_CYCLE_DIR`` should be agreed between
 different sub-systems of the workflow; typically they are named for the
 file-generating tasks, and the file-consuming tasks should know to look there.