WIP: New tutorial

docs/tutorial.rst

@@ -1385,8 +1385,84 @@ This will cause ReFrame to stop after a specified amount of failures.
 Managing the configuration
 ==========================
 
+Adding more systems to the ReFrame configuration file will soon make it quite big.
+ReFrame can build its final configuration by combining several smaller configuration files.
+For example, you could maintain a configuration file per system and keep logging and general settings in a different file.
+You can chain the configuration files by passing multiple times the :option:`-C` option.
+Alternatively, you can set the :envvar:`RFM_CONFIG_PATH` variable to specify the directories where ReFrame will search for configuration files.
+The configuration files in this case must be named as ``settings.py``.
 
-.. _logging:
+In the following, we have split the ``cluster_perflogs.py`` in three different configuration files as follows:
+
+.. code-block:: console
+
+    config/multifile/
+    ├── common
+    │   └── settings.py
+    ├── environments
+    │   └── settings.py
+    └── pseudo-cluster
+        └── settings.py
+
+Since the configuration file names are normalized, we could use the :envvar:`RFM_CONFIG_PATH` environment variable instead of the :option:`-C` option:
+
+.. code-block:: bash
+
+   export RFM_CONFIG_PATH=$(pwd)/config/multifile/common:$(pwd)/config/multifile/environments:$(pwd)/config/multifile/pseudo-cluster
+
+
+Inspecting the loaded configuration
+-----------------------------------
+
+ReFrame offers the very convenient :option:`--show-config`, that allows you to inspect the actual loaded configuration or query configuration values.
+Indeed having set the environment variable :envvar:`RFM_CONFIG_PATH`, running
+
+.. code-block:: bash
+
+   reframe --show-config
+
+will show us the current configuration.
+Note that the loaded configuration resolves to the auto-detected system.
+Even if we load a configuration file with multiple files, the :option:`--show-config` option will show the configuration of the current system:
+
+.. code-block:: bash
+
+   reframe -C :config/baseline.py --show-config
+
+Notice that the ``tutorialsys`` was not matched and therefore the current system is the ``generic``.
+
+.. note::
+
+   Using the ``:`` before the configuration filename passed to the :option:`-C` option, instructs ReFrame to drop any configuration built so far from the :envvar:`RFM_CONFIG_PATH`.
+
+
+The :option:`--show-config` option takes also an optional argument which will allows you to select a specific configuration parameter:
+
+.. code-block:: bash
+
+   reframe --show-config=systems/0/name
+
+.. code-block:: json
+
+   "pseudo-cluster"
+
+You can also use the :option:`--show-config` option to retrieve the default value of a configuration parameter, even if this is not defined in the configuration file:
+
+.. code-block:: bash
+
+   reframe --show-config=general/0/trap_job_errors
+
+.. code-block:: json
+
+   false
+
+
+Scoping configuration options
+-----------------------------
+
+
+
+.. _Logging:
 
 Logging
 =======

examples/tutorial/config/multifile/common/settings.py

@@ -0,0 +1,32 @@
+# Copyright 2016-2023 Swiss National Supercomputing Centre (CSCS/ETH Zurich)
+# ReFrame Project Developers. See the top-level LICENSE file for details.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+site_configuration = {
+    'modes': [
+        {
+            'name': 'singlethread',
+            'options': ['-E num_threads==1']
+        }
+    ],
+    'logging': [
+        {
+            'handlers_perflog': [
+                {
+                    'type': 'filelog',
+                    'prefix': '%(check_system)s/%(check_partition)s',
+                    'level': 'info',
+                    'format': ('%(check_result)s,'
+                               '%(check_job_completion_time)s,'
+                               '%(check_system)s:%(check_partition)s,'
+                               '%(check_environ)s,'
+                               '%(check_perfvalues)s'),
+                    'format_perfvars': ('%(check_perf_value)s,'
+                                        '%(check_perf_unit)s,'),
+                    'append': True
+                }
+            ]
+        }
+    ]
+}

examples/tutorial/config/multifile/environments/settings.py

@@ -0,0 +1,27 @@
+# Copyright 2016-2023 Swiss National Supercomputing Centre (CSCS/ETH Zurich)
+# ReFrame Project Developers. See the top-level LICENSE file for details.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+site_configuration = {
+    'environments': [
+        {
+            'name': 'baseline',
+            'features': ['stream']
+        },
+        {
+            'name': 'gnu',
+            'cc': 'gcc',
+            'cxx': 'g++',
+            'features': ['openmp'],
+            'extras': {'omp_flag': '-fopenmp'}
+        },
+        {
+            'name': 'clang',
+            'cc': 'clang',
+            'cxx': 'clang++',
+            'features': ['openmp'],
+            'extras': {'omp_flag': '-fopenmp'}
+        }
+    ]
+}

examples/tutorial/config/multifile/pseudo-cluster/settings.py

@@ -0,0 +1,31 @@
+# Copyright 2016-2023 Swiss National Supercomputing Centre (CSCS/ETH Zurich)
+# ReFrame Project Developers. See the top-level LICENSE file for details.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+site_configuration = {
+    'systems': [
+        {
+            'name': 'pseudo-cluster',
+            'descr': 'Example Slurm-based pseudo cluster',
+            'hostnames': ['login'],
+            'partitions': [
+                {
+                    'name': 'login',
+                    'descr': 'Login nodes',
+                    'scheduler': 'local',
+                    'launcher': 'local',
+                    'environs': ['gnu', 'clang']
+                },
+                {
+                    'name': 'compute',
+                    'descr': 'Compute nodes',
+                    'scheduler': 'squeue',
+                    'launcher': 'srun',
+                    'access': ['-p all'],
+                    'environs': ['gnu', 'clang']
+                }
+            ]
+        }
+    ]
+}