Understanding the "needs" command's meaning and documentation #1538

Why do we need needs when there's batch?

We can call task from the same or different packages in batch with -b. This seems to be the same thing.

There are several differences between them.

needs provides a way to call (a list of) other tasks from the same or another namespace from inside the task definitions (so those other tasks may be called only conditionally, for example). The called tasks also reuse the same server configuration as their caller task has (therefore it will reuse the existing open connection if there's any). It also doesn't execute any hooks of the called tasks.

batch provides a way to describe a named and strictly ordered list of tasks outside (or "on top" of) the task definitions. this batch can be later executed with rex -b batch_name on the command line and will call each of these tasks exactly as defined in the Rexfile (or modules), including their hooks. That means it will run those tasks on their default targets as defined, and will open a new connection to the targets for each task as described in the task definition. (It's also possible to run a batch from inside a task with run_batch if really needed).

I personally used it effectively to implement an alias for another task

Like most things in Perl, TIMTOWTDI. Of course in simple cases some building blocks that Rex provides may seem similar or even interchangeable to some extent. For these kind of calls, there's also:

• do_task to call an other task "as-is" from inside a task
• run_task to call an other task with optionally overriding their default target, and/or pass a different set of parameters to them

I expect it would be possible to deprecate do_task in favor of the more complete run_task sometime in the future. For now, both of them are provided for backwards compatibility.

(but then we could have an alias option for a task in the future to do this elegantly)

We can discuss the use cases, syntax and implications that proposed feature separately.

It's POD is confusing, probably wrong, which will require to create an issue + pull request + CHANGES file modifications so creating a discussion for now before knowing what to do:

image

It is often hard to find a condensed way to represent all the supported features of a command in a way that pleases everyone. I would say that the pattern today is:

• the original author of a command tried their best to describe the intended and/or most common use case for the command in its "signature" as the list element
• then any additional features later were added to the more verbose description with examples

What I see at first glance is that the examples are correct. If the BAREWORD vs $package difference, and/or the extra comma in the list entry prevents you from using needs correctly, please open a bug. We can then review this specific command and overhaul its documentation (choose a more common default use case, and/or add more examples if there are missing ones).