From 8c980772d5d93c131a9dd4215ee9fbc61b09e79e Mon Sep 17 00:00:00 2001 From: Cedric Beust Date: Mon, 18 Apr 2016 03:05:59 -0800 Subject: [PATCH 1/3] 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()

From ed0248ce3f71335f55a4abeb0056f2c7872e47b0 Mon Sep 17 00:00:00 2001
From: Cedric Beust 
Date: Tue, 19 Apr 2016 05:04:20 -0800
Subject: [PATCH 2/3] Clarify task dependencies.

---
 plug-in-development/index.html | 61 +++++++++++++++-------------------
 1 file changed, 26 insertions(+), 35 deletions(-)

diff --git a/plug-in-development/index.html b/plug-in-development/index.html
index 094fe2b..13d014d 100644
--- a/plug-in-development/index.html
+++ b/plug-in-development/index.html
@@ -470,7 +470,7 @@ The @Task annotation accepts the following attributes:
     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".
+    "reverseDependsOn". You can see "reverseDependsOn" as a way to insert your task before an existing task.
 

 

     Orderings, controlled by "runBefore" and "runAfter" merely specify an ordering
@@ -479,58 +479,49 @@ The @Task annotation accepts the following attributes:
     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.
-

-

-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:
+Here are a few different scenarios to illustrate how the three attributes work for the task example:
 

 

 Result of the command ./kobaltw --dryRun compile
 

 
-        
+        
+        
-        
+        
-    
-    
-        
+        
+    
+    
+        
+        
+        
+
     

     
Configuration for exampleTaskConfiguration for example
         ResultNote
     

     
runBefore = "compile"dependsOn = "compile"
         
-
kobalt-line-count:clean
-kobalt-line-count:exampleTask
-kobalt-line-count:compile

+
clean
+compile
+example

         
runAfter = "compile"
         
-
kobalt-line-count:clean
-kobalt-line-count:compile

+            Make the "example" task depend on "compile".
         		
     

     

         reverseDependsOn = "compile"
         
-
kobalt-line-count:clean
-kobalt-line-count:compile
-kobalt-line-count:exampleTask

+
clean
+example
+compile

         		
+            Insert the "example" task before "compile".
+        
runAfter = "compile"
+
clean
+compile

+        		
+            Make "example" run after "compile" but only if it's invoked explicitly.
+        

 

 
Dynamic tasks


From 7ce5c4e85a52e52a1d14619691f64a2819ee54bb Mon Sep 17 00:00:00 2001
From: Cedric Beust 
Date: Wed, 18 May 2016 23:23:15 -0800
Subject: [PATCH 3/3] Move a section around.

---
 home/index.html | 47 +++++++++++++++++++++++++----------------------
 1 file changed, 25 insertions(+), 22 deletions(-)

diff --git a/home/index.html b/home/index.html
index 19de4d6..804cf4f 100644
--- a/home/index.html
+++ b/home/index.html
@@ -77,27 +77,6 @@
 

 
Features

 
-
Build file auto-completion in your IDE

-

-  Since Kobalt's build files are actual Kotlin files, not only can you leverage auto-completion
-  to write your build files but the full power of your IDEA is at your fingertips to write
-  these files in any way you see fit: using expressions, conditionals, classes, extension functions,
-  constants... The sky is the limit!
-

-

-  Kobalt uses Kotlin's type safe builder pattern to offer a DSL that's extremely similar to Gradle
-  and minimalistic while allowing you to switch to full Kotlin code whenever necessary.
-

-

-  Here is an example of the auto-completion dialog:
-

-

-
-

-

-  And see the following section to get a feel for Kobalt's build file syntax.
-

-
 
Clean, minimal syntax for build files

 

 For example, here is JCommander's entire build file:
@@ -133,7 +112,31 @@ val jcommander = project {
 

   This build file also includes a directive to upload your artifacts to Bintray automatically.
 

-  
Incremental tasks

+
+
+
Build file auto-completion in your IDE

+

+  Since Kobalt's build files are actual Kotlin files, not only can you leverage auto-completion
+  to write your build files but the full power of your IDEA is at your fingertips to write
+  these files in any way you see fit: using expressions, conditionals, classes, extension functions,
+  constants... The sky is the limit!
+

+

+  Kobalt uses Kotlin's type safe builder pattern to offer a DSL that's extremely similar to Gradle
+  and minimalistic while allowing you to switch to full Kotlin code whenever necessary.
+

+

+  Here is an example of the auto-completion dialog:
+

+

+  
+

+

+  And see the following section to get a feel for Kobalt's build file syntax.
+

+
+
+          
Incremental tasks

 

   Most of Kobalt's core tasks are incremental, which means that if you run them without having changed anything, they will be skipped. The support for incremental tasks is also trivial to add for plug-in developers, which guarantees that your builds with Kobalt will always be as fast as they can be.