Bazel: 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.

[beasleyr-vmw]

~External contributors would benefit from guidelines for what (not) to do when adding to bazel_tools (see https://github.com/bazelbuild/bazel/issues/8738#issuecomment-581163441).~

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".