diff --git a/docs/config_reference.rst b/docs/config_reference.rst
index d03e882f53..de39df008c 100644
--- a/docs/config_reference.rst
+++ b/docs/config_reference.rst
@@ -323,6 +323,14 @@ System Partition Configuration
- ``upcrun``: Parallel programs will be launched using the `UPC `__ ``upcrun`` command.
- ``upcxx-run``: Parallel programs will be launched using the `UPC++ `__ ``upcxx-run`` command.
+ .. tip::
+
+ .. versionadded:: 4.0.0
+
+ ReFrame also allows you to register your own custom launchers simply by defining them in the configuration.
+ You can follow a small tutorial `here `__.
+
+
.. js:attribute:: .systems[].partitions[].access
:required: No
diff --git a/docs/tutorial_advanced.rst b/docs/tutorial_advanced.rst
index f23c7fd143..f56e5cacc9 100644
--- a/docs/tutorial_advanced.rst
+++ b/docs/tutorial_advanced.rst
@@ -576,8 +576,6 @@ The trick here is to replace the parallel launcher with the local one, which pra
The :func:`~reframe.core.backends.getlauncher` function takes the `registered `__ name of a launcher and returns the class that implements it.
You then instantiate the launcher and assign to the :attr:`~reframe.core.schedulers.Job.launcher` attribute of the job descriptor.
-An alternative to this approach would be to define your own custom parallel launcher and register it with the framework.
-You could then use it as the scheduler of a system partition in the configuration, but this approach is less test-specific.
Adding more parallel launch commands
====================================
@@ -628,6 +626,65 @@ Let's see how the generated job script looks like:
The first three ``srun`` commands are emitted through the :attr:`prerun_cmds` whereas the last one comes from the test's :attr:`executable` attribute.
+Adding a custom launcher to a partition
+=======================================
+
+.. versionadded:: 4.0.0
+
+An alternative to the approaches above would be to define your own custom parallel launcher and register it with the framework.
+You could then use it as the launcher of a system partition in the configuration and use it in multiple tests.
+
+Each `launcher `__ needs to implement the :func:`~reframe.core.launchers.JobLauncher.command` method and can optionally change the default :func:`~reframe.core.launchers.JobLauncher.run_command` method.
+
+As an example of how easy it is to define a new parallel launcher backend, here is the actual implementation of the ``mpirun`` launcher:
+
+.. code:: python
+
+ from reframe.core.backends import register_launcher
+ from reframe.core.launchers import JobLauncher
+
+
+ @register_launcher('mpirun')
+ class MpirunLauncher(JobLauncher):
+ def command(self, job):
+ return ['mpirun', '-np', str(job.num_tasks)]
+
+
+The :func:`~reframe.core.launchers.JobLauncher.command` returns a list of command tokens that will be combined with any user-supplied `options `__ by the :func:`~reframe.core.launchers.JobLauncher.run_command` method to generate the actual launcher command line.
+Notice you can use the ``job`` argument to get job-specific information that will allow you to construct the correct launcher invocation.
+
+If you use a Python-based configuration file, you can define your custom launcher directly inside your config as follows:
+
+.. code:: python
+
+ from reframe.core.backends import register_launcher
+ from reframe.core.launchers import JobLaucher
+
+
+ @register_launcher('slrun')
+ class MySmartLauncher(JobLauncher):
+ def command(self, job):
+ return ['slrun', ...]
+
+ site_configuration = {
+ 'systems': [
+ {
+ 'name': 'my_system',
+ 'partitions': [
+ {
+ 'name': 'my_partition',
+ 'launcher': 'slrun'
+ ...
+ }
+ ],
+ ...
+ },
+ ...
+ ],
+ ...
+ }
+
+
Flexible Regression Tests
-------------------------
diff --git a/reframe/core/launchers/__init__.py b/reframe/core/launchers/__init__.py
index d187c9a74f..f59a1ed362 100644
--- a/reframe/core/launchers/__init__.py
+++ b/reframe/core/launchers/__init__.py
@@ -15,11 +15,11 @@ class JobLauncher(abc.ABC):
A job launcher is the executable that actually launches a distributed
program to multiple nodes, e.g., ``mpirun``, ``srun`` etc.
- .. warning::
-
- Users may not create job launchers directly.
.. note::
+ .. versionchanged:: 4.0.0
+ Users may create job launchers directly.
+
.. versionchanged:: 2.8
Job launchers do not get a reference to a job during their
initialization.
diff --git a/reframe/schemas/config.json b/reframe/schemas/config.json
index b8e1561f9e..5490b55280 100644
--- a/reframe/schemas/config.json
+++ b/reframe/schemas/config.json
@@ -251,12 +251,7 @@
]
},
"launcher": {
- "type": "string",
- "enum": [
- "alps", "ibrun", "local", "mpirun",
- "mpiexec", "srun", "srunalloc", "ssh",
- "upcrun", "upcxx-run", "lrun", "lrun-gpu"
- ]
+ "type": "string"
},
"access": {
"type": "array",