Differences and similarities between tasks and teams in SBT

Question

Recently, I was instructed not to confuse the tasks and teams with this answer , which made me first realize that there was even a difference. During my research, the confusion rose even more, and I must admit that I can not clearly separate both! I believe that the main problem is that the terminology is often used synonymously, but the concepts are different, very related and very similar to some. Reading the documentation did not bring me much satisfaction. I don’t want to explicitly indicate problems in the sbt documentation, so don’t get me wrong, but I want you to see my current progress. I asked my questions during the trip and added a number in front of him.

Study

The first resource I consulted was the Tasks and Commands section in the documentation, which pointed only to a getting started guide.

Beginning of work

The getting started guide doesn't really explain the differences in this exact name. In particular, Defining Tasks and Settings seems to be even more confusing, with the difference between the types; Setting[T] , Setting[Task[T]] , Task[T] and terminology of keys and their corresponding types.

They say that

A TaskKey[T] defines a task. Tasks are operations such as compile or package . They can return Unit (Unit Scala for void ), or they can return a value related to the task, for example package is TaskKey[File] , and its value is the jar file that it creates.

This is a bit strange, but now normal, so Tasks are TaskKey instances with a result of type T

Each time you start a task, for example, by typing compile at the interactive sbt prompt, sbt will re-run any tasks involved exactly once.

Thus, any task is available at the sbt prompt. So where is the difference in the team? In subsequent sections, both seem to be used synonymously, for example here . The Settings Details section further describes:

Remember that some parameters describe tasks, so this approach also creates dependencies between tasks.

Thus, tasks can depend on each other, entered by the settings.

The plugin expands the definition of the assembly, most often adding new settings. New settings may be new tasks. For example, a plugin might add a codeCoverage task that will generate a test coverage report.

Plugins can introduce new tasks using the settings.

Also remember from the definition of the .sbt assembly that the parameter has a fixed value until the project is reloaded, and the task is recalculated for each "task execution" (each time someone enters a command in the sbt interactive help or in batch mode).

This makes me think that the command is just what is indicated in the sbt prompt or directly to the terminal using batch mode. Then the idea arises that the team acts only as a shallow front for each task. # 1 Does each task have a corresponding team?

By defining running plugins, automatic plugins can be used as a convenient way to add custom tasks and commands to all subprojects.

Here, I think that teams can be configured separately - similar to tasks. However, the Running Commands section talks about creating aliases for teams or tasks, but doesn't say anything about tasks. Again, I feel that these concepts may be the same, although I know that they are both different.

Tasks

The following is a list of tasks related functions on the Tasks page:

• Integrating with the settings system, tasks can be added, deleted and changed as easily and flexibly as settings.
• Input tasks use parser combinators to determine the syntax of their arguments. This allows you to use flexible syntax and tabs in the same way as commands.
• Tasks create values. Other tasks can access the value of tasks by invoking the value on it in the task definition.
• Perhaps a dynamic change in the structure of the task schedule. Tasks can be entered into the execution schedule based on the result of another task.
• There are ways to handle the failure of a task, similar to try / catch / finally.
• Each task has access to its own Journal, which by default saves the journal for this task at a more detailed level than originally printed on the screen.

Over the functions, he further says:

Settings are evaluated during project loading. Tasks are performed on demand, often in response to a user command.

So, some tasks can be initiated in other ways.

Teams

Finally, the command page reads:

A “command” is similar to a task: its named operation, which can be performed from the sbt console.

So now I think that any call to a given task or command coming from an invitation or sbt package is invoked by the command. Regardless of whether the command controls the task or instance of the command. # 2. Does it make sense to distinguish between definition and call level to reduce ambiguity? For example: at the call level, this is all a command, but at the definition level it is Command or TaskKey .

Here is a code snippet showing the general anatomy of a command definition:

 val action: (State, T) => State = ??? val parser: State => Parser[T] = ??? val command: Command = Command("name")(parser)(action) 

Thus, Command action is a state transition that makes it very difficult in terms of functional programming. Compared to the fact that the task that is an instance of TaskKey[T] is more like a simple function that returns a result of type T Paragraph 3 in the list of functions indicates that tasks produce values ​​that make me think of tasks more like pure functions, without generating only some minor side effects, such as logging as described in paragraph 6, except for tasks with a return type Unit .

However, the implementation of the commands takes as its parameter the entire state of the assembly (represented by the state) and calculates the new state. This means that the command can view or change other sbt parameters, for example. As a rule, you resort to a team when you need to do something impossible in a normal task.

So, I understand that the team has improved somewhat for some cases. Then I ask myself: Do tasks and teams perform the same set of functions related to the list of task functions, as obvious point 2? Clause 1 states that arbitrary changes to settings may occur due to the integration of the settings system, is that not true for commands? The same is for points 4, 5 and 6. # 3 Can someone clarify this, especially the limitations and give reasons for when I should objectively prefer using commands over tasks or an example (counter), if not?

Answer 1

Try to use tasks every time you can. They are easier to understand and easier to write.

From the documentation:

As a rule, you resort to a team when you need to do something impossible in a normal task.

This, of course, does not help if it is not indicated what are the limitations of the tasks. However, I personally understood this: if you want to manipulate state builds, you can use the commands.

An example of this is when you want to run a task with different settings.

Tasks give you access to other settings and tasks, commands also give you access to state and allow you to manipulate it. However, this is due to ignorance of other developers and increased complexity.

There are times when something can be expressed as a task or a team. Here I would take an approach to choosing one that feels easier.

Answer 2

As far as I understand the Command API, there are some things that you cannot do (easily) using Command. The command does not return a value. Thus, you cannot easily create another task based on the result of the command. It may be possible to simulate it by keeping the results in state and retrieving it from there in another command (or task), but I don’t know SBT well enough to say that it is really possible - and it is also pretty cool.

I used commands as a device for organizing - to define a shortcut for commonly used sequences of commands. For example - Set javaOptions to a specific value - run a specific main class with some arguments (which may be command arguments) - Then reset javaOptions (setting) to their old value.

This ordering can also be done manually, of course, but the command is good for wrapping this entire partial template.