Updating the runfiles tree structure

Once https://github.com/bazelbuild/bazel/issues/848 is resolved, runfiles (files your binary uses during runtime, not for compilation) will be accessible via the path ../repo-name/path/to/your/stuff.

For example, if you have the rule:

cc_binary(
    name = "my-program",
    src = ["prog.cc"],
    data = ["@gov_nyc//phonebook:year2007.csv"],
)

then your program should access year2007.csv during runtime via the path ../gov_nyc/phonebook/year2007.csv.

Migrating your code

Before this change, your code would access year2007.csv using the path external/gov_nyc/phonebook/year2007.csv, not ../gov_nyc/phonebook/year2007.csv, so it will have to be modified to look in the new location. To make this change easier, Bazel is making runfiles available in both locations (external/gov_nyc and ../gov_nyc) for Bazel 0.2.3. Please use the ../_repository-name_ syntax going forward and ensure that your existing code uses it by trying building with the --nolegacy_external_runfiles flag:

bazel build --nolegacy_external_runfiles //foo:bar

Then test to make sure the end product still works.

In 0.2.4, --nolegacy_external_runfiles will become the default (you will still be able to specify --legacy_external_runfiles to get the old behavior), then in the next release the option will be removed.

Why this is happening

Basically, this change makes it much easier to use runfiles from external repositories.

The details: Bazel creates a directory to run your binary in, which is where the runfiles are put. If you built a binary like //foo/bar:baz, you can find the runfiles tree at bazel-bin/foo/bar/baz.runfiles/.

Using the old runfiles scheme with the example above, this directory would contain:

my-program.runfiles/
    my_workspace_name/
        my-program
        external/
            gov_nyc/
                phonebook/
                    year2007.csv

When you run my-program, it runs in the my_workspace_name directory, so it can access year2007.csv via the relative path external/gov_nyc/phonebook/year2007.csv.

However, when nyc.gov employees are working on their programs, their runfiles tree will look like:

thing.runfiles/
    gov_nyc/
        phonebook/
            year2007.csv

So they'll be assuming that they can access runfiles relative to the gov_nyc directory. To make their code usable as an external repository, they'll either have to check both phonebook/year2007.csv and external/gov_nyc/phonebook/year2007.csv or their code won't work if anyone else uses it as an external repository.

This change makes all repositories "equals" in the runfiles tree: they are now structured like:

my-program.runfiles/
    my_workspace_name/
        my-program
    gov_nyc/
        phonebook/
            year2007.csv

This way, everyone can access runfiles via the path ../gov_nyc/ and it will work whether gov_nyc is the "main" repository or an external repository.

The --legacy_runfiles_structure flag temporarily makes this structure look like:

my-program.runfiles/
    my_workspace_name/
        my-program
        external/
            gov_nyc/
                phonebook/
                    year2007.csv
    gov_nyc/
        phonebook/
            year2007.csv

Incompatibility with no workspace name

This change means that all repositories, including the local one, must have a workspace name. If one is not provided in the WORKSPACE file, the name __main__ will be used instead.

If you are currently not setting a workspace name, your binary might be looking for runfiles in a now-nonexistent location: directly under the .runfiles directory.

Previous structure with no workspace name provided:

x.runfiles/
    foo

New structure:

x.runfiles/
    __main__/
        foo

Thus, to make your binaries work, you should:

1. Set a workspace name in your WORKSPACE file (workspace(name = "com_example_whatever")).
2. Update the paths your binaries use to access runfiles from foo to com_example_whatever/foo.

Let us know if you have any questions or issues about these changes.