Clarify --compilation_mode usage

[ashi009]

Description of the problem / feature request:

compilation_mode is great, but few people know, understand and use it.

For rule developers, it's common to have a rule that produces different outputs based on debugging/optimization settings. So we ended with having attributes like debug, compress etc on the rules, which is annoying and also less optimal to use for various reasons.

Throughout the entire rule design totorial, configuration_mode is not mentioned. Without knowing such a configuration exists, people find their own way to solve an already solved problem.

Also per the user manual:

This option takes an argument of fastbuild, dbg or opt, and affects various C/C++ code-generation options, such as the level of optimization and the completeness of debug tables. Bazel uses a different output directory for each different compilation mode, so you can switch between modes without needing to do a full rebuild every time.

It gives the impression that compilation_mode only works for C/C++ builds, but it's something that affects all rules that support it. Having those misleading statements are not promoting the usage of this feature.

[dslomov]

@hlopko feel free to redirect to Configurability or Starlark

[oquenchil]

It is true that --compilation_mode is not specific to C++. I guess the issue here is about updating the docs to make that clear and to expose it to Starlark if it's not already exposed.