Document providers in C/C++ rules and return values in cc_common
- Dominant language
- Java
- Stars
- 25.8k
- Forks
- 4.6k
- Avg merge
- 2d 20h
- Merged PRs (30d)
- 72
Description
### Description of the request:
Need to document providers exposed from native rules cc_library, cc_binary (and others) and returned values from cc_common functions.
### Feature requests: what underlying problem are you trying to solve with this feature?
I want to write my own rules in C++ project, which uses cc_library, cc_binary as an input, and there is no documentation about how I can use output of those rules. Also my rules are trying to use cc_common utilities and there is a lack of documentation too.
As an example:
**BUILD**
```
package(default_visibility = ["//visibility:public"])
load("//:my_rule.bzl", "my_rule")
cc_library(
name = "bar",
srcs = ["main.cc"],
)
my_rule(
name = "dump",
input = ":bar",
)
```
**my_rule.bzl**
```
def _my_rule(ctx):
input = ctx.attr.input
print(input.output_groups.dynamic_library)
my_rule = rule(
implementation = _my_rule,
attrs = {
"input": attr.label(),
},
)
```
There is no information in documentation that shared library is stored in `.output_groups.dynamic_library`.
About cc_common: there are many places which not properly documented in https://docs.bazel.build/versions/0.28.0/skylark/lib/cc_common.html , for example
1) Return value of `cc_common.link` (`CcLinkingOutputs`) is not documented
2) Return value of `cc_common.compile` (`tuple`) is not documented (there is no information about content of the tuple)
I think documentation need to be more detailed.
Contributor guide
Research direction
Start with the cc_common documentation at the linked legacy URL, then review the documentation for cc_library and cc_binary providers. Document the exposed providers and the return contents of cc_common.link and cc_common.compile; the work is done when users can determine how to consume these outputs in custom rules.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp
- Domain
- build-system, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100