Clarify how to vary `out` filename based on configuration

[mobileink]

Custom output requires that the out attribute be configurable. E.g.

    out = select({
        "//:xml": "ocaml_archive.xml",
        "//conditions:default": "ocaml_archive.md"
    }),

[brandjon]

You're talking about the stardoc rule? The attr/documentation says:

    "out": attr.output(
        doc = "The (markdown) file to which documentation will be output.",
        mandatory = True,
    ),

This suggests a .xml file doesn't make sense (though maybe it works fine with the right template).

But more importantly, I don't believe the attr.output attribute type can be configurable, or that there's anything a Starlark rule can do to change that. This is because outputs declared by attributes are determined to exist during the loading phase, before configuration information is known.

As for the general issue of how to produce one output file or another depending on configuration: I don't know offhand, but it might be possible using a custom rule that sits on top of the stardoc rule. Perhaps the rule would just copy the desired file to have the appropriate name, and return it in the files of DefaultInfo. Or maybe it would use output groups to allow you to choose between files on the command line.

[mobileink]

On Mon, Jan 11, 2021 at 8:58 PM Jon Brandvein notifications@github.com wrote:

You're talking about the stardoc rule? The attr/documentation says:

"out": attr.output(
    doc = "The (markdown) file to which documentation will be output.",
    mandatory = True,
),

This suggests a .xml file doesn't make sense (though maybe it works fine with the right template).

That docstring should be changed. Markdown is the default, but it is not required. It's relatively easy to write custom templates, although it did take a little digging to figure out the api (e.g. '${attribute.getProviderNameGroupList()}'); but that stuff could easily be documented. XML emission works just fine, I'm emitting DITA code.

But more importantly, I don't believe the attr.output attribute type can be configurable, or that there's anything a Starlark rule can do to change that. This is because outputs declared by attributes are determined to exist during the loading phase, before configuration information is known.

Yep. I came across a similar observation searching for how to use 'select' with genrules: https://github.com/bazelbuild/bazel/issues/281

As for the general issue of how to produce one output file or another depending on configuration: I don't know offhand, but it might be possible using a custom rule that sits on top of the stardoc rule. Perhaps the rule would just copy the desired file to have the appropriate name, and return it in the files of DefaultInfo. Or maybe it would use output groups to allow you to choose between files on the command line.

That might work, thanks. For now I'm just using a shell script to rename the files, which I have to use anyway to copy the output from bazel-bin to docs.