incompatible_no_rule_outputs_param: disable outputs param of rule function

[c-parsons]

This flag disables the outputs parameter on the rule() function.

Flag: --incompatible_no_rule_outputs_param

Motivation
Output Map Madness outlines some problems and inconsistencies in using this pattern, and there are also a couple of github issues (#2883 and #5581) on this matter.

Additional details in #6241

Migration
Use OutputGroupInfo specify output files instead.

For example, replace:

def _my_rule_impl(ctx):
    ...

my_rule = rule(
    implementation = _my_rule_impl,
    outputs = {“bin”: “%{name}.exe”},
)

with:

def _rule_impl(ctx):
    ...
    bin_name = ctx.attr.name + “.exe”
    bin_output = ctx.actions.declare_file(bin_name)
    # bin_output will, as before, need to be the output of an action
    ...
    return [OutputGroupInfo(bin = depset([bin_output])]

my_rule = rule(
    implementation = _my_rule_impl,
)

Note that this migration approach does not automatically let you specify these outputs by label. For example, you will notice that, with this exact approach, you cannot specify the ".exe"-suffix as its own label.
In order to preserve this implicit-output functionality, you will need to use attr.output with a macro-specified default. For example:

def _rule_impl(ctx):
    ...
    bin_output = ctx.outputs.bin_output
    # bin_output will, as before, need to be the output of an action
    ...
    return [OutputGroupInfo(bin = depset([bin_output])]

_my_rule = rule(
    implementation = _my_rule_impl,
    attrs = {
       "bin_output" : attr.output(),
    }
)

def my_rule(name, **kwargs):
    my_rule(name = name,
        bin_output = name + ".exe",
        **kwargs)

[c-parsons]

I've spoken to authors of rules_apple (@thomasvl @allevato @sergiocampama) who have established some pains with respect to this change. These are issues we should work to resolve before proceeding with this migration.

1. It's unfortunate and a pain to make rule-name consistent with macro name. The only way is to define the rule in another file, export it as a different name, and call that from the macro. That is:

my_rule_private.bzl:

my_rule = rule(...)

my_rule.bzl:

load(':my_rule_private.bzl', _my_rule="my_rule")
def my_rule(name, **kwargs):
    _my_rule(name = name, kwargs)

Loading an additional bzl file has performance implications, and this pattern requires annoying separation between related bits of code.

Possible workaround: One workaround would be if we allow rules to define their proper name to be different than their exported name.
For example:

_my_rule = rule(exported_name = "my_rule", ...)

def my_rule(name, **kwargs):
    _my_rule(name = name, kwargs)

2. This requires writing documentation in parallel for a macro and the rule it requires. Stardoc should look to the rule documentation and no macro documentation should be required! However, skylint aggressively indicates these macros must be documented.
   (Except, it may be best if one were able to document default values of output attributes alongside the macro which controls it -- but this should merely enhance the existing rule documentation, not require duplicating the rule's docs!)

This seems a high priority feature for Stardoc, and perhaps a blocker for this migration.

For completeness, we also discussed a question I have been asked before regarding this migration:
Q: Aren't macros a thing we want to avoid? Why is the recommendation to use a macro to set output values?
A: No, Starlark team discourages complex macros that users can depend on. If there is a 1:1 correspondence between macro and subsequent rule, the macro should be OK for users to depend on. That is all this migration plan suggests.

[allevato]

Aside: rules_apple/rules_swift can look into using output groups as well (which would avoid the need for a macro), but those output groups can't be referenced directly by other rules (i.e., there's no equivalent to :Foo.ipa), right?

[c-parsons]

That's correct -- the only way to make optional outputs specifiable by label is to use attr.output or attr.output_list, whose values must be set by macro.

FWIW, the correct approach is to use both output groups and attr.output. The former allows a user to build Foo.ipa by specifying:

bazel build //my:Foo --output_groups=ipa

and the latter allows building Foo.ipa by specifying:

bazel build //my:Foo.ipa

(or similarly a dependency on //my:Foo.ipa from another target)