Doc for @bazel_tools

[olafure]

Bazel documentation is missing an explanation the "@bazel_tools" built in repository.

[panzhongxian]

What's the link of doc for @bazel_tools ? thx.

[dslomov]

We did add documentation for http_archive etc; shall we add more?

[laurentlb]

The documentation doesn't say what is @bazel_tools, so yes.
We should mention it's a magic repository that's part of Bazel binary.

[ghost]

External contributors would benefit from guidelines for what (not) to do when adding to bazel_tools (see #8738 (comment)).

EDIT: Okay, so consensus seems that adding to bazel_tools is a no-go. (Unsure of implications for #8738, but that discussion should stay with that issue.)

[laurentlb]

I think it's better if we don't add anything to @bazel_tools.
Most files should live outside the Bazel binary.

[jin]

+1 we should be removing targets from @bazel_tools as much as possible.

cc @alandonovan who ran into issues with the JDK / Java rules side of the embedded repository recently.

[alandonovan]

I recently added a "jni" target to @bazel_tools//java/jdk, and was struck that (a) this repo's public API is essentially undocumented, and (b) that declarations added to it take a full Bazel release before they can be used, which imposes a surprisingly subtle obstacle to evolution.

I agree we should get rid of this repo. Although there may still be a need for a mechanism to expose built-in symbols to certain rule sets (Java, for example) owned by the Bazel team, exposing these symbols directly to the whole world is a liability.

[blais]

I just encountered this @bazel_tools and got surprised by its existence as well.

[nickgeorge]

+1, as an internal google user, this was still very surprising to me that there is a magic @-target, that is a requirement to know about for things as basic as http_archive. This needs to be documented well.

[dzintars]

Not sure is it important there, but i came across this error/warning when run ibazel on Linux without any relations to apple ecosystem:

iBazel [3:29PM]: Querying for files to watch...
Loading: 0 packages loaded
ERROR: /home/dzintars/.cache/bazel/_bazel_dzintars/73eb78004b7f7dbbf7672ded04d50930/external/bazel_tools/tools/osx/BUILD:80:19: every rule of type xcode_config_alias implicitly depends upon the target '@bazel_tools//tools/objc:host_xcodes', but this target could not be found because of: no such target '@bazel_tools//tools/objc:host_xcodes': target 'host_xcodes' not declared in package 'tools/objc' defined by /home/dzintars/.cache/bazel/_bazel_dzintars/73eb78004b7f7dbbf7672ded04d50930/external/bazel_tools/tools/objc/BUILD.bazel
ERROR: /home/dzintars/.cache/bazel/_bazel_dzintars/73eb78004b7f7dbbf7672ded04d50930/external/bazel_tools/tools/osx/BUILD:80:19: every rule of type xcode_config_alias implicitly depends upon the target '@bazel_tools//tools/objc:host_xcodes', but this target could not be found because of: no such target '@bazel_tools//tools/objc:host_xcodes': target 'host_xcodes' not declared in package 'tools/objc' defined by /home/dzintars/.cache/bazel/_bazel_dzintars/73eb78004b7f7dbbf7672ded04d50930/external/bazel_tools/tools/objc/BUILD.bazel
ERROR: Evaluation of subquery "deps(set(//platform/web/shell/server))" failed (did you want to use --keep_going?): errors were encountered while computing transitive closure
Loading: 1 packages loaded
Loading: 1 packages loaded
iBazel [3:29PM]: Bazel query failed: exit status 7

So i am looking forward to resolve this "warning".

[stabai]

I feel like the documentation here (which is the best documentation I've found) should have more detailed explanation, and should also be included on every page that talks about built-in rules, like the BUILD encyclopedia.

Based on discussion here, it seems that this list is only expected to shrink in the future, which is good. Skylib is also not obvious to find, and it should be. I see the wisdom in that being imported separately, but it's still pretty core functionality. But bazel_tools being in this weird built-in but not native state is incredibly confusing.

[devesh-bedrock]

Does anyone know where I can find details on @bazel_tools//platforms:target_platform and @bazel_tools//platforms:host_platform?

+1 to improving to documentation on everything inside @bazel_tools.

[justonelov]

Thank you

…

On Mon, Jun 6, 2022, 1:23 PM Shawn Tabai ***@***.***> wrote: I feel like the documentation here <https://bazel.build/rules#embedded-rules> (which is the best documentation I've found) should have more detailed explanation, and should also be included on every page that talks about built-in rules, like the BUILD encyclopedia <https://bazel.build/reference/be/overview>. Based on discussion here, it seems that this list is only expected to shrink in the future, which is good. Skylib is also not obvious to find, and it should be. I see the wisdom in that being imported separately, but it's still pretty core functionality. But bazel_tools being in this weird built-in but not native state is incredibly confusing. — Reply to this email directly, view it on GitHub <#4301 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AMZPU2YCCSOBTIZGZU5C7B3VNYX25ANCNFSM4EIIZ3BQ> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[github-actions]

Thank you for contributing to the Bazel repository! This issue has been marked as stale since it has not had any activity in the last 1+ years. It will be closed in the next 90 days unless any other activity occurs. If you think this issue is still relevant and should stay open, please post any comment here and the issue will no longer be marked as stale.

[Jasha10]

It will be closed in the next 90 days unless any other activity occurs.

~activity~

[korjek]

still active

[codeno]

y

[lberki]

@meteorcloudy my inclination would be to close this bug as "not planned": @bazel_tools is an implementation detail and we are planning to deprecate it (slowly), so I'd much rather not advertise its existence. WDYT?

[meteorcloudy]

Hmm, I think there is still value to document it given it's widely used (e.g. for hosting some repo rules) and the level of interest shown by 👍. Understanding how the bazel_tools is set up and used could help user resolve some issues.