From 8c980772d5d93c131a9dd4215ee9fbc61b09e79e Mon Sep 17 00:00:00 2001 From: Cedric Beust Date: Mon, 18 Apr 2016 03:05:59 -0800 Subject: [PATCH] Update the task dependency section. --- plug-in-development/index.html | 51 ++++++++++++++++++++++------------ 1 file changed, 33 insertions(+), 18 deletions(-) diff --git a/plug-in-development/index.html b/plug-in-development/index.html index 7995665..094fe2b 100644 --- a/plug-in-development/index.html +++ b/plug-in-development/index.html @@ -436,7 +436,7 @@ Tasks are provided by plug-ins and can be invoked from the command line, e.g. @Task annotation. Here is an example: 

-@Task(name = "lineCount", description = "Count the lines", runBefore = arrayOf("compile"))
+@Task(name = "lineCount", description = "Count the lines", dependsOn = arrayOf("compile"))
 fun lineCount(project: Project): TaskResult {
     // ...
     return TaskResult()
@@ -452,36 +452,51 @@ The @Task annotation accepts the following attributes:
     
The name of the task, which will be used to invoke it from the command line.

     
description

     
The description of this command, which will be displayed if the user invokes the usage for the kobaltw command.

+    
dependsOn

+    
A list of all the tasks that this task depends on.

+    
reverseDependsOn

+    
Make the following tasks depend on this task.

     
runBefore

     
A list of all the tasks that this task should run prior to.

     
runAfter

     
A list of all the tasks that should run before this task does.

-    
alwaysRunAfter

-    
A list of all the tasks that will always be run after this task if it's invoked.

 
 

 

-The difference between runAfter and alwaysRunAfter is subtle but important. runAfter
-is just a declaration of dependency. It's basically the reverse of runBefore but it's useful in case
-you are not the author of the task you want to run before (if you were, you would just use the runBefore
-annotation on it). Since you can't say "a runBefore b" because you don't own task "a",
-you say "b runAfter a".
+    Kobalt defines two different concepts for tasks: dependencies and orderings. And for each of this concept,
+    you can define the relation to go in one direction or the other.
 

 

-For example, compileTest is declared as a runAfter for the task compile.
+    If your task cannot run until another task has run, you need to declare a dependency. Dependencies cause
+    additional tasks than those requested to be executed. For example, "assemble" depends on "compile", which means that whenever you invoke "assemble", "compile"
+    will be automatically run first. This is a dependency and it is controlled by "dependsOn" and
+    "reverseDependsOn".
+

+

+    Orderings, controlled by "runBefore" and "runAfter" merely specify an ordering
+    but do not pull new tasks in. This is how you tell Kobalt "In case task X is run, run my task before it
+    (or after)". But if task X doesn't run, your task will not be run either (unless it's explicitly requested
+    by the user).
+

+

+    The reverse direction attributes "reverseDependsOn" and "runAfter" are useful
+    when you want to declare a dependency/ordering on a task that you do not control, and that you can therefore
+    not modify.
+

+

+

+For example, compileTest is declared as "dependsOn" the task compile.
 This means that it doesn't make sense to run compileTest unless compile has run first.
 However, if a user invokes the task compile, they probably don't want to invoke compileTest,
 so a dependency is exactly what we need here: invoking compileTest will trigger compile
 but not the other way around.
 

 

-However, there are times where you want to define a task that will always run after a given task.
-For example, you could have a signJarFile task that should always be invoked if someone builds a jar
-file. You don't expect users to invoke that target explicitly, but whenever they invoke the assemble
-target, you want your signJarFile target to be invoked. When you want such a task to always be invoked
-even if the user didn't explicitly request it, you should use alwaysRunAfter.
-Note that there is no alwaysRunBefore annotation since runBefore
-achieves the same functionality.
+There are times where you want to define a task that will always run after a given task.
+For example, you could have a "signJarFile" task that should always be invoked if someone builds a jar
+file. You don't expect users to invoke that target explicitly, but whenever they invoke the "assemble"
+target, you want your "signJarFile" target to be invoked. When you want such a task to always be invoked
+even if the user didn't explicitly request it, you should use "reverseDependsOn".
 

 

 Here are a few different scenarios to illustrate how the three attributes work for the task exampleTask:
@@ -510,7 +525,7 @@ kobalt-line-count:compile
- alwaysRunAfter = "compile" + reverseDependsOn = "compile" 
kobalt-line-count:clean
 kobalt-line-count:compile
@@ -537,7 +552,7 @@ override fun tasksFor(context: KobaltContext) = listOf(
     DynamicTask(
         name = "dynamicTask",
         description = "Description",
-        alwaysRunAfter = listOf("compile"),
+        reverseDependsOn = listOf("compile"),
         closure = { project: Project ->
             println("Running dynamicTask")
             TaskResult()