Add workaround for mirror/fcm make tasks conflicting with symlink dirs (#692)

Add workaround for mirror/fcm make tasks conflicting with symlink dirs

* Tidy symlink dirs docs
* Add to spellcheck dictionary

Author: MetRonnie

src/7-to-8/major-changes/cylc-install.rst

@@ -114,6 +114,36 @@ use :cylc:conf:`flow.cylc[scheduler]install`.
 
 See :ref:`the user guide <RemoteInit>` for more details.
 
+.. warning::
+
+   If you have tasks that mirror to a remote platform (such as
+   `FCM make <FCM_>`__ tasks), this can cause conflicts with
+   :ref:`symlink directory setup <SymlinkDirs>`.
+
+   You can find out if symlink directories are configured for the platform by
+   running::
+
+      cylc config -i '[install][symlink dirs][<platform-name>]'
+
+   The recommended workaround is to use a "dummy" task that runs on the
+   particular platform before any such mirror tasks in order to setup symlink
+   directories, but without running anything.
+
+   For example:
+
+   .. code-block:: cylc
+
+      [scheduling]
+          [[graph]]
+              R1 = hpc_init => fcm_make
+
+      [runtime]
+          [[hpc_init]]
+              platform = <platform-name>
+              script = true
+
+
+
 
 Migrating From ``rose suite-run``
 ---------------------------------

src/dictionaries/words

@@ -173,6 +173,7 @@ subcommands
 subdir
 subdirectories
 subdirectory
+subprocess
 subprocesses
 subshell
 subshelled

src/reference/config/writing-platform-configs.rst

@@ -112,7 +112,7 @@ require remote initialization.
            install target = localhost
 
 Our Cylc scheduler does not have a job runner defined. Any job submitted to
-this ``localhost`` platform will run as a background job. Users can now set 
+this ``localhost`` platform will run as a background job. Users can now set
 :cylc:conf:`flow.cylc[runtime][<namespace>]platform` = ``pbs_cluster`` to run
 pbs jobs.
 
@@ -280,15 +280,17 @@ the login nodes, without the concern of selecting a specific platform.
 
 Symlinking Directories
 ----------------------
+
 To minimize the disk space used by ``~/cylc-run``, set
-:cylc:conf:`global.cylc[install][symlink dirs]`.
-The entire workflow directory can be symlinked, using the config item ``run`` 
-The following sub-directories  are also available for configuration:
+:cylc:conf:`global.cylc[install][symlink dirs]` to offload files onto other
+locations. The entire :term:`run directory` can be symlinked, as well as
+certain sub-directories.
 
-   * log
-   * share
-   * share/cycle
-   * work
+* ``run`` - the :term:`run directory` itself
+* ``log``
+* ``share`` (see :term:`share directory`)
+* ``share/cycle`` (typically used by `Rose`_ tasks)
+* ``work`` (see :term:`work directory`)
 
 These should be configured per :term:`install target`.
 
@@ -303,7 +305,7 @@ you could write the following in ``global.cylc``:
            [[[localhost]]]
                log = /somewhere/else
 
-This would result in the following file structure on the Cylc Scheduler:
+This would result in the following file structure on the Cylc scheduler host:
 
 .. code-block:: none
 
@@ -421,7 +423,7 @@ will store the workflow under ``/g/data/foo`` and submit jobs under project
 
 You can also forward variables from the server to other platforms. You should
 first ensure the variable is available on the server, e.g. by also forwarding
-the variable to ``[[localhost]]``. 
+the variable to ``[[localhost]]``.
 
 This setting only affects the task submission (e.g. ``qsub``) which may use
 environment variables to set default directives. To set a variable once the
@@ -439,4 +441,3 @@ task has started see
             # Here qsub has been configured to read from $PROJECT
             ssh forward environment variables = PROJECT
             submit method = pbs
-

src/user-guide/installing-workflows.rst

@@ -157,14 +157,6 @@ sub-directories as symlinks to other locations. This is a useful way of
 offloading data onto other drives to limit the disk space taken up by
 ``~/cylc-run``.
 
-Directories that can be individually symlinked are:
-
-* ``log``
-* ``share``
-* ``share/cycle``
-* ``work``
-* the :term:`run directory` itself
-
 The symlink targets are configured per install target in
 :cylc:conf:`global.cylc[install][symlink dirs]`. For more information see
 :ref:`SymlinkDirsSetup`