tasks: add PREREQ_FOR

In some cases, it is useful to specify a task that would run before
another one, if the other task is also running. For instance, this could
ensure that a certain item is configured prior to being used, but only
for certain environments.

Signed-off-by: Stephen Brennan <[email protected]>

Author: brenns10

doc/guide/tasks.rst

@@ -93,6 +93,17 @@ functions which are available to you:
   script should not run again. It will detect a previous success, and exit with
   code 0. Note that this will still allow you to re-run a failed task.
 
+- ``PREREQ_FOR <other task>`` - this declares that your task is a
+  prerequisite of another. It can be thought of as the inverse of
+  ``DEPENDS_ON``, but with one important caveat. This relationship only applies
+  if the other task is actually loaded and run by Yo at the same time as this
+  one. For example, suppose task ``A`` contains ``PREREQ_FOR B``. Then:
+
+  - Specifying task ``A`` will not automatically run task ``B``
+  - Similarly, specifying task ``B`` will not automatically run ``A``
+  - However, if task ``A`` and ``B`` are both specified to run, then Yo will
+    ensure that A runs to completion before task ``B`` begins.
+
 These functions can be used anywhere in your script, however bash syntax such as
 quoting or variable expansion is not respected when Yo locates them. So, while
 the following is valid bash, it won't work with Yo:

yo/data/yo-tasks/test-deps

@@ -33,8 +33,8 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-DEPENDS_ON test-task
 MAYBE_DEPENDS_ON test-non-existing-task
 MAYBE_DEPENDS_ON test-existing-task
+DEPENDS_ON test-task
 sleep 10
 echo completed

yo/data/yo-tasks/test-prereq

@@ -0,0 +1,38 @@
+# Copyright (c) 2025, Oracle and/or its affiliates.
+#
+# The Universal Permissive License (UPL), Version 1.0
+#
+# Subject to the condition set forth below, permission is hereby granted to any
+# person obtaining a copy of this software, associated documentation and/or data
+# (collectively the "Software"), free of charge and under any and all copyright
+# rights in the Software, and any and all patent rights owned or freely
+# licensable by each licensor hereunder covering either (i) the unmodified
+# Software as contributed to or provided by such licensor, or (ii) the Larger
+# Works (as defined below), to deal in both
+#
+# (a) the Software, and
+# (b) any piece of software and/or hardware listed in the
+#     lrgrwrks.txt file if one is included with the Software (each a "Larger
+#     Work" to which the Software is contributed by such licensors),
+#
+# without restriction, including without limitation the rights to copy, create
+# derivative works of, display, perform, and distribute the Software and make,
+# use, sell, offer for sale, import, export, have made, and have sold the
+# Software and the Larger Work(s), and to sublicense the foregoing rights on
+# either these or other terms.
+#
+# This license is subject to the following condition: The above copyright notice
+# and either this complete permission notice or at a minimum a reference to the
+# UPL must be included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+PREREQ_FOR test-existing-task
+sleep 10
+echo completed

yo/data/yo_tasklib.sh

@@ -35,6 +35,10 @@ RUN_ONCE() {
     fi
 }
 
+PREREQ_FOR() {
+    true
+}
+
 # Setup the "$ORAVER" variable for Oracle Linux
 if [ -f /etc/oracle-release ] && grep '6\.' /etc/oracle-release; then
     ORAVER=6

yo/main.py

@@ -484,13 +484,15 @@ class YoTask:
     script: str
     dependencies: t.List[str]
     conflicts: t.List[str]
+    prereq_for: t.List[str]
 
     @classmethod
     def create_from_string(
         cls, name: str, script: str, path: str = "(memory)"
     ) -> "YoTask":
         dependencies = []
         conflicts = []
+        prereq_for = []
         all_tasks = list_tasks()
         lines = script.split("\n")
         for i in range(len(lines)):
@@ -509,7 +511,11 @@ def create_from_string(
                         "MAYBE_DEPENDS_ON", "# MAYBE_DEPENDS_ON"
                     )
                 lines[i] = line
-        return YoTask(name, path, "\n".join(lines), dependencies, conflicts)
+            elif line.startswith("PREREQ_FOR"):
+                prereq_for.append(line.split(None, maxsplit=1)[1])
+        return YoTask(
+            name, path, "\n".join(lines), dependencies, conflicts, prereq_for
+        )
 
     @classmethod
     @lru_cache(maxsize=None)
@@ -532,6 +538,10 @@ def load(cls, name: str) -> "YoTask":
             script = f.read()
         return cls.create_from_string(name, script, path=path)
 
+    def insert_prereq(self, other: str) -> None:
+        self.dependencies.append(other)
+        self.script = f"DEPENDS_ON {other}\n{self.script}"
+
 
 @lru_cache(maxsize=1)
 def list_tasks() -> t.List[str]:
@@ -607,51 +617,67 @@ def _task_run(ctx: YoCtx, inst: YoInstance, task: YoTask) -> None:
 def run_all_tasks(
     ctx: YoCtx, inst: YoInstance, tasks: t.Iterable[t.Union[YoTask, str]]
 ) -> None:
-    # Tasks can have dependencies. We need to be sure to load the full set of
-    # dependencies in the list of tasks we're given. We also need to verify
-    # there are no circular dependencies. And it's nice to launch them in order
-    # that will satisfy their dependencies, but the "DEPENDS_ON" function should
-    # successfully handle waiting until all depnedencies are completed anyway.
-
-    # 0: not visited, 1: visiting, 2: finished visit
+    # The caller may specify tasks as either strings or YoTask instances, for
+    # convenience. Let's get everything into a "name_to_task" dict.
+    name_to_task: t.Dict[str, YoTask] = {}
+    for task in tasks:
+        if isinstance(task, str):
+            name_to_task[task] = YoTask.load(task)
+        else:
+            name_to_task[task.name] = task
+
+    # Tasks may have dependencies. Let's go through every task, and their
+    # dependencies, and load them all. At this point, we're not yet checking
+    # whether there are any circular dependencies: just loading them.
+    tasks_to_load = list(name_to_task.values())
+    for task in tasks_to_load:
+        for name in task.dependencies:
+            if name not in name_to_task:
+                name_to_task[name] = YoTask.load(name)
+                tasks_to_load.append(name_to_task[name])
+
+    # Now we have loaded the complete set of tasks that should run. Some tasks
+    # may appoint themselves as "prerequisites" for another. We need to insert
+    # this dependency relationship so that the script is updated, and so that
+    # the circular dependency detection knows about it. We can also use this
+    # opportunity to detect conflicts.
+    for task in name_to_task.values():
+        for name in task.prereq_for:
+            if name in name_to_task:
+                name_to_task[name].insert_prereq(task.name)
+        for name in task.conflicts:
+            if name in name_to_task:
+                raise YoExc(f"Task {task.name} conflicts with {name}")
+
+    # Now all tasks are loaded, and prerequisites have been marked. Use a
+    # topological sort to verify that no circular dependencies are present. Here
+    # we use a recursive traversal because honestly, if you specify enough tasks
+    # to trigger a recursion error, then I would like to receive that bug
+    # report!
     name_to_visit: t.Dict[str, int] = collections.defaultdict(int)
-    # output ordering
     ordered_tasks: t.List[YoTask] = []
 
-    def visit(task_or_name: t.Union[YoTask, str]) -> None:
-        if isinstance(task_or_name, str):
-            name: str = task_or_name
-            task: t.Optional[YoTask] = None
-        else:
-            name = task_or_name.name
-            task = task_or_name
-        if name_to_visit[name] == 2:
+    def visit(task: YoTask) -> None:
+        if name_to_visit[task.name] == 2:
             # already completed, skip
             return
-        if name_to_visit[name] == 1:
+        if name_to_visit[task.name] == 1:
             # currently visiting, not a DAG
             raise YoExc("Tasks express a circular dependency")
 
-        name_to_visit[name] = 1
-        if not task:
-            task = YoTask.load(name)
+        name_to_visit[task.name] = 1
         for dep_name in task.dependencies:
-            visit(dep_name)
-        name_to_visit[name] = 2
+            visit(name_to_task[dep_name])
+        name_to_visit[task.name] = 2
         ordered_tasks.append(task)
 
-    for name in tasks:
-        visit(name)
-
-    # Now ordered_tasks contains the order in which we should launch them.
-    # Verify that there are no conflicts
-    all_task_names = {t.name for t in ordered_tasks}
-    for task in ordered_tasks:
-        for conflict in task.conflicts:
-            if conflict in all_task_names:
-                raise YoExc(f"Task {task} conflicts with {conflict}")
+    for task in name_to_task.values():
+        visit(task)
 
-    # Do the thing!
+    # Now ordered_tasks contains the order in which we should launch them.  This
+    # is just a nice-to-have: even if we launched them out of order, the
+    # DEPENDS_ON function would enforce the order of execution. Regardless,
+    # let's start the tasks.
     for task in ordered_tasks:
         _task_run(ctx, inst, task)