Upstream `github.com/phst/runfiles` as `@io_bazel_rules_go//go/runfiles`

[fmeum]

rules_go currently doesn't offer a way to discover runfiles following the standard procedures for runfiles discovery. There is https://pkg.go.dev/github.com/bazelbuild/rules_go/go/tools/bazel, but due to it predating the coordinated efforts to provide consistent runfiles libraries for all languages, it uses a non-standard procedure and doesn't interoperate well with the other libraries. It also invokes a bit too much magic that makes it prone to unexpected issues (e.g. it searches the working directory first before looking up the runfiles variables).

A proper replacement has been available as https://pkg.go.dev/github.com/phst/runfiles for quite some time now, so I would propose to upstream it (and would offer to do the work). According to the "Deploying rules" guide, this runfiles library should be available under @io_bazel_rules_go//go/runfiles (Gazelle could probably be taught to pick it up automatically).

[achew22]

Reading through the linked Bazel Runfiles Libraries doc I think I would like a little bit more authoritative of a citation around the expected structure of the runfiles library. "Deploying Rules" is an authoritative source for me and has me convinced that @io_bazel_rules_go//go/runfiles is in fact the correct place for the code to live, but if there is a mandated interface, I'd like that interface to be written down and in the mainline bazel docs so we don't end up having to support 3 versions (the original version, the version you wrote, and the version that replaced Laszlo's 2018 design doc).

As a proposed fix for this, could we send a PR to update https://github.com/bazelbuild/bazel/blob/master/site/docs/skylark/deploying.md filling in the Runfiles library section with the expected API? That way we, the bazel community, will have a canonical resource for discussing this in the future.

What do you think?

[fmeum]

I agree that the runfiles libraries are currently severely underdocumented. I have derived my knowledge mostly from the actual implementations in mainline Bazel (e.g., https://github.com/bazelbuild/bazel/blob/master/tools/java/runfiles/Runfiles.java and https://github.com/bazelbuild/bazel/blob/master/tools/cpp/runfiles/runfiles_src.h).

Which of these (or both) would you like me to do prior to upstreaming the runfiles library?

1. Add a short section to https://github.com/bazelbuild/bazel/blob/master/site/docs/skylark/deploying.md that explains the API of a runfiles library in abstract terms: Essentially, there will be an rlocation function mapping runfiles paths to paths on disk as well as an env function that returns the environment variables that should be propagated to subprocesses.
2. Add a detailed account of the actually implemented version of the runfiles discovery algorithm. It differs slightly between languages due to legacy behavior (e.g. JAVA_RUNFILES existed before RUNFILES_DIR), but is overall very similar across the four languages that provide it (C++, Java, Python, Go). I wouldn't know what a good place for this would be though and it would be a somewhat more laborious task.

[philsc]

Any thoughts on this? The rules_go implementation is the only one we use that breaks when used in a rules_docker container. The bash library and the Python library work without any problems in containers.