Understanding the "needs" command's meaning and documentation

[rwp0]

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.

I personally used it effectively to implement an alias for another task (but then we could have an alias option for a task in the future to do this elegantly):

task 'restart_proftpd', group => 'testing', sub {
  service sshd => 'stop';
  service proftpd => 'restart';
  service sshd => 'start';
};

task 'restart_sshd', group => 'testing', sub {
  needs main => 'restart_proftpd';
};

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:

[ferki]

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:

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).

[rwp0]

hmm... so needs acts like Perl's use in this case?:

use Package qw(LIST);

Tested that, and it's not the case, opening a bug.

[ferki]

hmm... so needs acts like Perl's use in this case?:

use Package qw(LIST);

That might be a good approximation for the simple cases, yes. Though this analogy might be dangerous to memorize as a general expectation because needs doesn't support syntax like use if or use VERSION.

Tested that, and it's not the case, opening a bug.

As mentioned there that's not a needs bug, but caused by failing to import needs into the scope of the newly declared main package. Therefore it throws a syntax error during compilation time. Minimum fix is to add use Rex::Commands; below package main;.

[rwp0]

thanks for the explanation, that still fails with use v5.36; (unlike with 5.32 or 5.34)

[ferki]

Oh, I already replied on your follow-up in the other bug:

It's a nice find 👍 but a different issue 🙃

use v5.36; disables the indirect perl feature, and that apparently may break some functionality. Quick fix is to add use feature 'indirect'; after use v5.36;.

To avoid mixing up topics, it's probably best to open a new bug for any further investigation.

Let's also try to keep information flow in a single place, please - I don't see a need to duplicate these things in both a discussion and an issue.