[bazel.build] Problem with /reference/be/general

Page link:

https://bazel.build/reference/be/general

Problem description (include actual vs expected text, if applicable):

I think the genrule examples should be clearer in explaining the difference between srcs and tools especially because genrule srcs are different from srcs in most other rules. I assumed that srcs would be interpreted as something executable if the target pointed to an executable because the docs mention that all prereqs are built before running the genrule, but that's not really how it works.

genrule( name = "concat_all_files", srcs = [ "//some:files", # a filegroup with multiple files in it ==> $(locations) "//other:gen", # a genrule with a single output ==> $(location) ], outs = ["concatenated.txt"], cmd = "cat $(locations //some:files) $(location //other:gen) > $@", ) I when I read this I thought //some:files could potentially be targets that produce runfiles but they should not be. Further down the page in the srcs section This attributes is not suitable to list tools executed by the cmd; use the [tools](https://bazel.build/reference/be/general#genrule.tools) attribute for them instead. I assumed this referred to files being executed by srcs in cmd (like a script calling another tool), not whatever is getting executed by bash. Maybe a quick example that explicitly rules out calling srcs in cmd would make it clearer.

Where do you see this issue? (include link to specific section of the page, if applicable)

https://bazel.build/reference/be/general#genrule_examples

Any other information you'd like to share?

If you are seeing "Cannot find .runfiles directory" this mistake might be why