bazelbuild / bazelbuild/bazel

Document providers in C/C++ rules and return values in cc_common

Open
#9,147 1 comment 0 reactions 0 assignees View on GitHub
help wanted P3 team-Documentation team-Rules-CPP type: documentation (cleanup)
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.