Deal with ccache in PATH for bazel builds

[jwnimmer-tri]

When a user has the magic ccache directory in their $PATH, bazel shows weird error messages that don't indicate the root cause of the problem and then fails.

Given that ccache is essentially required to have a good experience when using the CMake backends (ninja, make, etc.), and we can't (or at least shouldn't) have CMake inject ccache onto the path for us, we should do our best to accommodate developers who need to use both build systems from time to time.

If possible, we should either fail-fast in the case of .../lib/ccache on the path, or even better we should automatically remove the entry or otherwise fix the compiler variable(s) so that bazel is happy.

Part of #3129.

[jwnimmer-tri]

FTR idea from another dev: if there's a good ccache env var to turn it off, that would be the easiest solution. That would depend on the failure being at runtime not sandbox time, though.

[jwnimmer-tri]

Related:

• Building with ccache fails with auto-configuration bazelbuild/bazel#1164
• cannot compile with ccache + gcc bazelbuild/bazel#1139
• error building bazel and tensorflow with ccache bazelbuild/bazel#1322

I am trying a few things locally to discover the best workaround.

[jwnimmer-tri]

Okay, while I think there may be cc_toolchain fixes to make this fail-fast or self-repair better, there doesn't seem to be a one-liner fix. I'm going to FAQ it and return later.

[jwnimmer-tri]

For now at least, I'll call the doc fix good enough. I think a toolchain fix is likely to be better done in a PR to upstream code that in our project.

We can revisit if we find lots of Drake Developers complaining.

[david-german-tri]

After a really epic onramp failure today, I'm reopening this.

[david-german-tri]

bazelbuild/bazel#1143 is an obstacle.