Bazel: Documentation on DefaultInfo is lacking

[endobson]

https://bazel.build/versions/master/docs/skylark/lib/globals.html#DefaultInfo

DefaultInfo doesn't describe what the fields one can set on it do. While something can be inferred from names, the difference between runfiles and default_runfiles is unclear as well as what files means.

[Globegitter]

Yep, it is very confusing how data_runfiles vs default_runfiles vs runfiles are meant to be used. It sounds to me like one can either use runfiles or data_runfiles and default_runfiles, where-as one could choose the latter just to be more granular. But then if the output file of the rule is in the default_runfiles rather than the data_runfiles, I get an exception java.lang.IllegalStateException: main program File:[[<execution_root>]bazel-out/k8-fastbuild/bin]testdata/nodejs_image.binary_bin.sh not included in runfiles, which is not clear just based on the docs. Also I have to use ctx.runfiles(transitive_files=...) rather than ctx.runfiles(files=...) to not get an error, which is also not clear.

Edit: In fact if I provide both data_runfiles and default_runfiles I seem to get above exception and the bazel server crashes.

[c-parsons]

Indeed, the current API is a bit messy and confusing, and there are multiple ways of doing the same thing.

I'll be mailing out a proposal document to clean this up to [email protected] probably by the end of the week.

[c-parsons]

Sorry for not explicitly following up.
I intended on addressing this in the doc here:
https://docs.google.com/document/d/14A9HK8Jn2jErMayLEE3nrNJIxNfZWN_slFbhgtS6-aM

But I admit I'm still a little unclear on the current distinction (and its significance) between default_runfiles and data_runfiles

lberki@, IIRC you might have some additional context as to data_runfiles, could you provide any details?

[lberki]

We have the concept in core. I'm not sure if it's for a good reason, though. "data" runfiles means "the runfiles if this target is depended on through the "data" attribute. So if you want to mimic the behavior of Java rules, you need to have that.

If I had my way, we would abolish the concept altogether by making the "unified runfiles" be the union of data and normal runfiles. I don't know off the bat, though, what collateral damage that would cause. I'd expect most of the harm to be the set of input files for certain tests becoming much larger.

[ash2k]

Would be great to change all the fields that currently return None to return empty values instead (empty depset and empty runfiles). That way rules will not have to deal with None - e.g. rules_docker currently does not check for None properly.

[Globegitter]

Yeah I would be curios to see how unified runfiles would look like - it would certainly make the API much simpler and easy to understand. If for some reason it is not possible to have unified runfiles it would probably help a lot to have clear examples demonstrating the differences, as the descriptions are quite abstract to me.

[endobson]

Another point on this that I just ran into:

DefaultInfo has an executable parameter which is undocumented. https://github.com/bazelbuild/bazel/blob/1a6a5a1b4a85f61b9b335ba098a7d2e087c64649/src/main/java/com/google/devtools/build/lib/analysis/DefaultInfo.java#L63

This is referenced in other docs as the preferred way to use it:
https://docs.bazel.build/versions/master/skylark/rules.html#outputs

This seems to have gotten lost when the docs lost the Constructor documentation between 1.1 and 1.2

https://docs.bazel.build/versions/1.2.0/skylark/lib/DefaultInfo.html

https://docs.bazel.build/versions/1.1.0/skylark/lib/DefaultInfo.html#DefaultInfo

[NonLogicalDev]

Can the constructor documentation get added back? This is super confusing to newcomers.

Can the documented flag be switched over here:
https://github.com/bazelbuild/bazel/blob/7891d3b4be8549f762f32308a4085f802e7608e5/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/DefaultInfoApi.java#L86

[c-parsons]

Seems we have a bug where all constructor documentation is being dropped: https://github.com/bazelbuild/bazel/issues/10848

I don't believe that flipping that line to documented = true will add the constructor documentation. I believe this is an infrastructure bug in our documentation generator.

[c-parsons]

A few notes:

• #10848 is fixed
• I submitted changes last year revamping the rules and runfiles documentation; this greatly improves description of DefaultInfo
• I'll follow up with a change to the DefaultInfo page to better-describe the constructor and getters.