conf: change suite.rc to flow.cylc

.gitignore

@@ -13,6 +13,7 @@ __pycache__/
 
 # processed suite definitions
 *.rc.processed
+*.cylc.processed
 
 # profiling
 .profiling

CHANGES.md

@@ -40,6 +40,12 @@ Fourth alpha release of Cylc 8.
 
 (See note on cylc-8 backward-incompatible changes, above)
 
+The filenames `suite.rc` and `global.rc` are now deprecated in favour of
+`flow.cylc` and `global.cylc` respectively
+([#3755](https://github.com/cylc/cylc-flow/pull/3755)). For backwards
+compatibility, the `cylc run` command will automatically symlink an existing
+`suite.rc` file to `flow.cylc`.
+
 ### Enhancements
 
 [#3515](https://github.com/cylc/cylc-flow/pull/3515) - spawn-on-demand: a more

cylc/flow/cfgspec/globalcfg.py

@@ -34,7 +34,7 @@
 # - value_type: value type (compulsory).
 # - default: the default value (optional).
 # - allowed_2, ...: the only other allowed values of this setting (optional).
-with Conf('flow.rc', desc='''
+with Conf('global.cylc', desc='''
     The global configuration which defines default Cylc Flow settings
     for a user or site.
 
@@ -43,11 +43,11 @@
        $ cylc get-global-config --sparse
 
 
-    Cylc will attempt to load the global configuration (flow.rc) from two
+    Cylc will attempt to load the global configuration (global.cylc) from two
     locations:
 
-    * ``/etc/cylc/flow/<CYLC_VERSION>/flow.rc``
-    * ``~/.cylc/flow/<CYLC_VERSION>/flow.rc``
+    * ``/etc/cylc/flow/<CYLC_VERSION>/global.cylc``
+    * ``~/.cylc/flow/<CYLC_VERSION>/global.cylc``
 
     If both files are present files will be loaded in this order so those
     lower down the list may override settings from those higher up.
@@ -56,8 +56,13 @@
 
     .. note::
 
-       The ``flow.rc`` file can be templated using Jinja2 variables.
+       The ``global.cylc`` file can be templated using Jinja2 variables.
        See :ref:`Jinja`.
+
+    .. note::
+
+       Prior to Cylc 8, ``global.cylc`` was named ``global.rc``, but that name
+       is no longer supported.
 ''') as SPEC:
 
     # suite
@@ -87,21 +92,21 @@
 
     # suite
     with Conf('cylc', desc='''
-        Default values for entries in the suite.rc ``[cylc]`` section.
+        Default values for entries in flow.cylc ``[cylc]`` section.
     '''):
         Conf('UTC mode', VDR.V_BOOLEAN, False, desc='''
-                Default for :cylc:conf:`suite.rc[cylc]UTC mode`.
+                Default for :cylc:conf:`flow.cylc[cylc]UTC mode`.
         ''')
         Conf('task event mail interval', VDR.V_INTERVAL, DurationFloat(300),
              desc='''
                 Default for
-                :cylc:conf:`suite.rc[cylc]task event mail interval`.
+                :cylc:conf:`flow.cylc[cylc]task event mail interval`.
         ''')
 
         with Conf('events', desc='''
             You can define site defaults for each of the following options,
             details of which can be found under
-            :cylc:conf:`suite.rc[cylc][events]`.
+            :cylc:conf:`flow.cylc[cylc][events]`.
         '''):
             Conf('handlers', VDR.V_STRING_LIST)
             Conf('handler events', VDR.V_STRING_LIST)
@@ -380,7 +385,7 @@
             ''')
             Conf('retrieve job logs', VDR.V_BOOLEAN, desc='''
                 Global default for
-                :cylc:conf:`suite.rc[runtime][<namespace>][remote]retrieve job
+                :cylc:conf:`flow.cylc[runtime][<namespace>][remote]retrieve job
                 logs`.
             ''')
             Conf('retrieve job logs command', VDR.V_STRING, 'rsync -a',
@@ -391,22 +396,22 @@
             ''')
             Conf('retrieve job logs max size', VDR.V_STRING, desc='''
                 Global default for the
-                :cylc:conf:`suite.rc[runtime][<namespace>][remote]retrieve job
+                :cylc:conf:`flow.cylc[runtime][<namespace>][remote]retrieve job
                 logs max size`.
                 the specified host.
             ''')
             Conf('retrieve job logs retry delays', VDR.V_INTERVAL_LIST,
                  desc='''
                 Global default for the
-                :cylc:conf:`suite.rc[runtime][<namespace>][remote]retrieve job
+                :cylc:conf:`flow.cylc[runtime][<namespace>][remote]retrieve job
                 logs retry delays`.
                 setting for the specified host.
             ''')
             Conf('task event handler retry delays', VDR.V_INTERVAL_LIST,
                  desc='''
                 Host specific default for
-                :cylc:conf:`suite.rc[runtime][<namespace>][events]handler retry
-                delays`.
+                :cylc:conf:`flow.cylc[runtime][<namespace>][events]handler
+                retry delays`.
             ''')
             Conf('tail command template',
                  VDR.V_STRING, 'tail -n +1 -F %(filename)s', desc='''
@@ -479,7 +484,7 @@
     # task
     with Conf('task events', desc='''
         Global site/user defaults for
-        :cylc:conf:`suite.rc[runtime][<namespace>][events]`.
+        :cylc:conf:`flow.cylc[runtime][<namespace>][events]`.
     '''):
         Conf('execution timeout', VDR.V_INTERVAL)
         Conf('handlers', VDR.V_STRING_LIST)
@@ -497,7 +502,7 @@
         Settings for the automated development tests.
 
         .. note::
-           The test battery reads ``flow-tests.rc`` instead of the normal
+           The test battery reads ``global-tests.cylc`` instead of the normal
            site/user global config files (from the same locations, however).
     '''):
         Conf('remote platform with shared fs', VDR.V_STRING, desc='''
@@ -592,7 +597,7 @@
     with Conf('authentication', desc='''
         Authentication of client programs with suite server programs can be
         configured here, and overridden in suites if necessary with
-        :cylc:conf:`suite.rc[cylc][authentication]`.
+        :cylc:conf:`flow.cylc[cylc][authentication]`.
 
         The suite-specific passphrase must be installed on a user's account to
         authorize full control privileges (see
@@ -693,7 +698,7 @@ class GlobalConfig(ParsecConfig):
 
     _DEFAULT = None
     _HOME = os.getenv('HOME') or get_user_home()
-    CONF_BASENAME = "flow.rc"
+    CONF_BASENAME = "global.cylc"
     SITE_CONF_DIR = os.path.join(os.sep, 'etc', 'cylc', 'flow', CYLC_VERSION)
     USER_CONF_DIR = os.path.join(_HOME, '.cylc', 'flow', CYLC_VERSION)
 

cylc/flow/cfgspec/suite.py

@@ -34,13 +34,19 @@
 REC_COMMAND = re.compile(r'(`|\$\()\s*(.*)\s*([`)])$')
 
 with Conf(
-    'suite.rc',
+    'flow.cylc',
     desc='''
         Defines a cylc suite configuration.
 
         Embedded Jinja2 code (see :ref:`Jinja`) must process to a valid
-        raw suite.rc file. See also :ref:`SuiteRCFile` for a descriptive
-        overview of suite.rc files, including syntax (:ref:`Syntax`).
+        raw flow.cylc file. See also :ref:`FlowConfigFile` for a descriptive
+        overview of flow.cylc files, including syntax (:ref:`Syntax`).
+
+        .. note::
+
+           Prior to Cylc 8, this was named ``suite.rc``, but that
+           name is now deprecated. The ``cylc run`` command will automatically
+           symlink an existing ``suite.rc`` file to ``flow.cylc``.
     '''
 ) as SPEC:
 
@@ -66,7 +72,7 @@
             A web URL to suite documentation.  If present it can be browsed
             with the ``cylc doc`` command. The string template
             ``%(suite_name)s`` will be replaced with the actual suite name.
-            See also :cylc:conf:`suite.rc[runtime][<namespace>][meta]URL`.
+            See also :cylc:conf:`flow.cylc[runtime][<namespace>][meta]URL`.
 
             Example:
 
@@ -201,14 +207,14 @@
 
             In date-time cycling, if you do not provide time zone information
             for this, it will be assumed to be local time, or in UTC if
-            :cylc:conf:`suite.rc[cylc]UTC mode` is set, or in the time zone
-            determined by :cylc:conf`suite.rc[cylc][cycle point time zone]`.
+            :cylc:conf:`flow.cylc[cylc]UTC mode` is set, or in the time zone
+            determined by :cylc:conf`flow.cylc[cylc][cycle point time zone]`.
 
             The string ``now`` converts to the current date-time on the suite
             host (adjusted to UTC if the suite is in UTC mode but the host is
             not) to minute resolution.  Minutes (or hours, etc.) may be
             ignored depending on the value of
-            :cylc:conf:`suite.rc[cylc]cycle point format`.
+            :cylc:conf:`flow.cylc[cylc]cycle point format`.
         ''')
         Conf('final cycle point', VDR.V_STRING, desc='''
             Cycling tasks are held once they pass the final cycle point, if
@@ -218,9 +224,9 @@
 
             In date-time cycling, if you do not provide time zone information
             for this, it will be assumed to be local time, or in UTC if
-            :cylc:conf:`suite.rc[cylc]UTC mode`
+            :cylc:conf:`flow.cylc[cylc]UTC mode`
             is set, or in the time zone determined by
-            :cylc:conf`suite.rc[cylc][cycle point time zone]`.
+            :cylc:conf`flow.cylc[cylc][cycle point time zone]`.
         ''')
         Conf('initial cycle point constraints', VDR.V_STRING_LIST, desc='''
             in a cycling suite it is possible to restrict the initial cycle
@@ -675,7 +681,8 @@
 
                 The top level share and work directory location can be changed
                 (e.g. to a large data area) by a global config setting (see
-                :cylc:conf:`flow.rc[hosts][<hostname glob>]work directory`).
+                :cylc:conf:`global.cylc[hosts][<hostname glob>]
+                work directory`).
 
                 .. note::
 
@@ -732,7 +739,7 @@
                         ``%(task_name)s`` will be replaced with the actual
                         suite and task names.
 
-                        See also :cylc:conf:`[meta]URL <suite.rc[meta]URL>`.
+                        See also :cylc:conf:`[meta]URL <flow.cylc[meta]URL>`.
 
                         Example:
 
@@ -855,7 +862,7 @@
             with Conf('events', desc='''
                 Cylc can call nominated event handlers when certain task
                 events occur. This section configures specific task event
-                handlers; see :cylc:conf:`suite.rc[cylc][events]` for
+                handlers; see :cylc:conf:`flow.cylc[cylc][events]` for
                 suite event handlers.
 
                 Event handlers can be located in the suite ``bin/`` directory,
@@ -1078,7 +1085,7 @@
                     script without evaluation or manipulation by cylc, so any
                     variable assignment expression that is legal in the job
                     submission shell can be used.  White space around the
-                    ``=`` is allowed (as far as cylc's suite.rc parser is
+                    ``=`` is allowed (as far as cylc's flow.cylc parser is
                     concerned these are just normal configuration items).
 
                     Examples::
@@ -1089,7 +1096,7 @@
                        WAZ = ${FOO%.jpg}.png
                        NEXT_CYCLE = $( cylc cycle-point --offset=PT6H )
                        ZAZ = "${FOO#bar}"
-                       # ^ quoted to escape the suite.rc comment character
+                       # ^ quoted to escape the flow.cylc comment character
                 ''')
 
             with Conf('directives', desc='''

cylc/flow/config.py

@@ -489,9 +489,9 @@ def __init__(
 
             self.cfg['scheduling']['special tasks'][s_type] = result
 
-        self.collapsed_families_rc = (
+        self.collapsed_families_config = (
             self.cfg['visualization']['collapsed families'])
-        for fam in self.collapsed_families_rc:
+        for fam in self.collapsed_families_config:
             if fam not in self.runtime['first-parent descendants']:
                 raise SuiteConfigError(
                     '[visualization]collapsed families: '
@@ -503,7 +503,7 @@ def __init__(
         elif is_reload:
             self.closed_families = []
         else:
-            self.closed_families = self.collapsed_families_rc
+            self.closed_families = self.collapsed_families_config
         for cfam in self.closed_families:
             if cfam not in self.runtime['descendants']:
                 self.closed_families.remove(cfam)
@@ -626,7 +626,7 @@ def __init__(
 
         # (Note that we're retaining 'default node attributes' even
         # though this could now be achieved by styling the root family,
-        # because putting default attributes for root in the suite.rc spec
+        # because putting default attributes for root in the flow.cylc spec
         # results in root appearing last in the ordered dict of node
         # names, so it overrides the styling for lesser groups and
         # nodes, whereas the reverse is needed - fixing this would
@@ -704,7 +704,7 @@ def __init__(
         self.mem_log("config.py: end init config")
 
     def process_initial_cycle_point(self):
-        """Validate and set initial cycle point from suiterc.
+        """Validate and set initial cycle point from flow.cylc.
 
         Sets:
             self.initial_point
@@ -1453,7 +1453,7 @@ def check_tasks(self):
         huge suites (several thousand tasks).
         Note:
           (a) self.cfg['runtime'][name]
-              contains the task definition sections of the suite.rc file.
+              contains the task definition sections of the flow.cylc file.
           (b) self.taskdefs[name]
               contains tasks that will be used, defined by the graph.
         Tasks (a) may be defined but not used (e.g. commented out of the
@@ -1571,10 +1571,10 @@ def generate_taskdefs(self, orig_expr, left_nodes, right, seq, suicide):
                 replicate(self.cfg['runtime'][name],
                           self.cfg['runtime']['root'])
                 if 'root' not in self.runtime['descendants']:
-                    # (happens when no runtimes are defined in the suite.rc)
+                    # (happens when no runtimes are defined in flow.cylc)
                     self.runtime['descendants']['root'] = []
                 if 'root' not in self.runtime['first-parent descendants']:
-                    # (happens when no runtimes are defined in the suite.rc)
+                    # (happens when no runtimes are defined in flow.cylc)
                     self.runtime['first-parent descendants']['root'] = []
                 self.runtime['parents'][name] = ['root']
                 self.runtime['linearized ancestors'][name] = [name, 'root']
@@ -1748,16 +1748,16 @@ def get_graph_raw(self, start_point_string, stop_point_string,
 
         if self.first_graph:
             self.first_graph = False
-            if not self.collapsed_families_rc and not ungroup_all:
+            if not self.collapsed_families_config and not ungroup_all:
                 # initially default to collapsing all families if
                 # "[visualization]collapsed families" not defined
                 group_all = True
 
         first_parent_descendants = self.runtime['first-parent descendants']
         if group_all:
             # Group all family nodes
-            if self.collapsed_families_rc:
-                self.closed_families = copy(self.collapsed_families_rc)
+            if self.collapsed_families_config:
+                self.closed_families = copy(self.collapsed_families_config)
             else:
                 for fam in first_parent_descendants:
                     if fam != 'root':

cylc/flow/etc/flow-tests.rc.eg → cylc/flow/etc/global-tests.cylc.eg

@@ -3,16 +3,17 @@
 #------------------------------------------------------------------------------
 # Some functional tests need to modify or ignore installed global configuration
 # values; they therefore ignore the standard site and user global config files
-# and start from a special flow-tests.rc file instead. These should contain the
-# minimal essential settings (e.g. for host names) needed to run at your site.
+# and start from a special global-tests.cylc file instead. These should contain
+# the minimal essential settings (e.g. for host names) needed to run at your
+# site.
 #
-# See documentation in flow.rc.eg
+# See documentation in global.cylc.eg
 #
 #------------------------------------------------------------------------------
-## GLOBAL flow-tests.rc FILE LOCATIONS:
+## GLOBAL global-tests.cylc FILE LOCATIONS:
 #----------------
 # SITE:
-#   /etc/cylc/flow/<CYLC-VERSION>/flow-tests.rc
+#   /etc/cylc/flow/<CYLC-VERSION>/global-tests.cylc
 # USER:
-#   $HOME/.cylc/flow/<CYLC-VERSION>/flow-tests.rc
+#   $HOME/.cylc/flow/<CYLC-VERSION>/global-tests.cylc
 #------------------------------------------------------------------------------