Implement directory based runfiles lookup [#130]

[mfarrugi]

Lookup based on java and python, API is a subset of Runfiles.java and looks similar to runfiles.py as well.

I punted on manifest-based lookup because I don't quite understand the usage; it's to work around symlink issues on windows?

This should fix osx usage, but I would like to see this pass CI before merging, so blocked on #131.

This fixes #112 and resolves #130.

[acmcarther]

Thanks for implementing this!

Comments below are mostly nits, but I did want to ask about having some example usage of this in @examples//. Or is that waiting on some other change?

[acmcarther]

I dont feel strongly about this, but we probably should conform to Rust idioms:

Suggested change

	pub fn create() -> io::Result<Self> {
	pub fn new() -> io::Result<Self> {

Unsure what Rust zeitgeist has to say about new methods not returning Self directly (though it's obviously justified here).

[mfarrugi]

runfiles.py struck me as unidiomatic as well, so I leaned towards looking the same as other runfiles libraries. I also don't feel strongly about this.

[acmcarther]

OK, matching python (in defying local norms) SGTM

[acmcarther]

Under what conditions would the path not be valid? I'm unclear on whether this just refers to non-existent paths, or if some bazel-related circumstances can arise to cause a file not to appear.

[mfarrugi]

I think this means that you can call rlocation on some path, and it will return xxx.runfiles/ + path regardless of path exists, depending on the type of Runfiles object.

[acmcarther]

Nit: I suspect you can remove the shadowing (which i detest, but others disagree) by just naming the PathBuf::from output to "binary_path" and making it mutable.

[acmcarther]

Why would this happen?

[mfarrugi]

a. If the executing binary is part of another's runfiles tree, eg. a py_binary calling out to our rust_binary.
b. Someone called the symlink under .runfiles to start the process.

I have also seen many binaries deployed with a merged .runfiles tree.

[acmcarther]

Nit: The control flow here strikes me as unusual. This seems to be breaking out of the loop { }, but it isn't obvious from code comments that we've reached a terminal state -- in reality, the above comment seems to indicate the opposite.

Perhaps the comment here should be revisited?

[mfarrugi]

Wrote the comment before flipping the if statement, will move it down.

[mfarrugi]

I removed the hello_runfiles example as part of this because it was redundant with the documentation and test in runfiles.rs -- what else would you like to see in an example?

[acmcarther]

Regd an example:

A personal usecase I have is similar to #79 -- include_bytes! for a genfile dependency. I don't think the default include! macros can take anything other than string literals though, so we'd have to go without the macro unless replacement macros were included in the crate.

A really good example might be one that genrule to serialize a value into a file and then deserializes it in the example, but that would require some deps.

Instead, here's a simpler one:
examples/runfiles/hello_world.txt
hello world!
examples/runfiles/example.rs

extern crate runfiles;
use runfiles::Runfiles;

fn main() {
  let fpath: PathBuf =
    Runfiles::create().unwrap().rlocation("examples/runfiles/hello_world.txt")
  let contents = {
    let file = File::open(&fpath).unwrap();
    let mut buf_reader = BufReader::new(file);
    let mut contents = String::new();
    buf_reader.read_to_string(&mut contents).unwrap();
    contents
  };
  assert_eq!(contents, "hello world!");
}

(% compiler errors)