rules_runfiles

KO | EN

gitlite — search

#javascript #hacktoberfest #ai #golang #rust #nodejs #windows #cli #kubernetes #awesome-list #pytorch #security #mcp #open-source

(★ 17)

Compile-time safe runfiles access for Bazel

rules_runfiles Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Compile-time safe runfiles access for Bazel

A key concept of Bazel is that of *runfiles*: the collection of files that a binary needs to have access to at runtime.
Runfiles are usually declared using the `data` attribute and are automatically propagated from dependencies.

How a binary can find its runfiles at runtime depends on the OS: While Bazel uses a tree of symlinks on Unix systems, it
usually falls back to a manifest file on Windows. Thus, the recommended way to look up runfiles is through the runfiles
libraries provided for all major languages under `@bazel_tools//tools/<lang>/runfiles`
or `@rules_<lang>//<lang>/runfiles`. These libraries all offer an `rlocation` function that maps the runfiles path of a
file, which is of the form `repository/path/to/pkg/filename`, to the actual location of the file at runtime.

This ruleset offers a convenient wrapper around the runfiles libraries that has the following advantages over using the
libraries directly:

* **Compile-time safety**:
  If your Bazel target compiles, it will find its runfiles at runtime.

* **Automatic cross-platform support**:
  `//foo:bar` is `libbar.so` on Linux, but `bar.dll` on Windows? With rules_runfiles, the runfiles path of the file will
  be available as a constant named after the label `//foo:bar`, which is independent of the particular target platform.

* **IDE completions**:
  rules_runfiles translates the Bazel package structure into generated, language-specific structures that work well with
  IDEs. For example, `//foo:bar` is available as `::runfiles::current_repo::foo::bar` (nested namespaces) in C++
  and `JavaRunfilesTargetName.current_repo.foo.bar` (nested classes) in Java.

* **Required for Bazel modules**:
  With Bazel's new module system (also known as bzlmod), the internal names of repositories depend on their declared
  versions as well as the particular way they are loaded. Since the names are part of the runfiles paths, these paths
  are no longer static and thus can no longer be hardcoded. rules_runfiles uses code generation together with a naming
  scheme that carefully avoids the internal names of repositories to allow consistent runfiles access from modules.

The following languages are currently supported:

* C++
* Java

Support for other languages is planned, suggestions and contributions are very welcome.

## Usage

### Step 0: `WORKSPACE` setup

```starlark
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "fmeum_rules_runfiles",
    sha256 = "057f42a28cccc4a27ba3d65f1b49ef734e95bd74f10c5a98d8812e7a0e663e00",
    strip_prefix = "rules_runfiles-0.1.1",
    url = "https://github.com/fmeum/rules_runfiles/archive/refs/tags/v0.1.1.tar.gz",
)
```

### Step 1: Declaring a `<lang>_runfiles` target

Create a `<lang>_runfiles` target with all the data dependencies you would usually specify on your `<lang>_binary`
or `<lang>_library` and reference it in the `deps` attribute. Here, `<lang>` is either `cc` (C++) or `java` (Java).

```starlark
load("@fmeum_rules_runfiles//runfiles:<lang>_defs.bzl", "<lang>_runfiles")

<lang>_runfiles(
    name = "foo_runfiles",
    data = [
        "data/test.txt",
        "data/dir",
        ":other_binary",
        "@other_repo//path/to/other:binary",
    ],     
)

<lang>_binary(
    name = "foo",
    deps = [
        ":foo_runfiles",
        ...
    ],
    ...
)

```

Note:

* Since the code generated by `rules_runfiles` uses the labels listed in the `data` attribute to refer to runfiles,
  every label must correspond to exactly one file. Rules such
  as [bazel-skylib's `select_file`](https://github.com/bazelbuild/bazel-skylib/blob/6e30a77347071ab22ce346b6d20cf8912919f644/rules/select_file.bzl#L39)
  can be used to break up targets into individual files.
* The `data` dependencies should not be repeated on the `<lang>_binary` or `<lang>_library` target.
* `<lang>_runfiles` targets are only visible from the package in which they are defined. Since they contain generated
  code that refers to the "current package", exposing them to other packages would lead to very confusing situations. If
  there is a larger list of data dependencies shared between multiple targets in different packages, consider exporting
  the list via a Starlark constant in a `.bzl` file instead.
* Use of Bazel 5.1.0 or higher is recommended as lower versions of Bazel include runfiles libraries that do not always
  find runfiles contained in directories that are themselves runfiles when using a manifest
  (https://github.com/bazelbuild/bazel/issues/14336).

### Step 2: Accessing the runfiles constants

**C++**: A `cc_runfiles` target with `name = "foo_runfiles"` provides a generated header `foo_runfiles.h` that can be
included via

```c++
#include "path/to/pkg/foo_runfiles.h"
```

This file contains a string constant for every label in the `data` attribute of the `cc_runfiles` rule, organized in
namespaces. When deriving the fully-qualified name of a constant, Bazel repositories and packages map to namespaces and
non-alphanumeric characters are replaced by underscores. There are also special namespaces for the current package, the
current repository and the main repository.

| Bazel label                | C++ constant                                   |
|----------------------------|------------------------------------------------|
| `:foo`                     | `::runfiles::current_pkg::foo`                 |
| `:dir/some-File.txt`       | `::runfiles::current_pkg::dir_some_File_txt`   |
| `//path/to/pkg:foo`        | `::runfiles::current_repo::path::to::pkg::foo` |
| `@foobar//path/to/pkg:foo` | `::runfiles::foobar::path::to::pkg::foo`       |
| `@//path/to/pkg:foo`       | `::runfiles::main_repo::path::to::pkg::foo`    |

The fully-qualified names of these constants can be shortened with `using` and `using namespace` directives.

**Java**: A `java_runfiles` target with `name = "foo_runfiles"` provides a generated class `FooRunfiles` (name converted
to CamelCase with special characters replaced with underscores). By default, this class is contained in a package
determined from the containing Bazel package by the same rules as `java_binary`'s `main_class`. It can be overriden with
the `package` attribute on `java_runfiles`.

This class contains a `String` constant for every label in the `data` attribute of the `java_runfiles` rule, organized
in nested classes. When deriving the fully-qualified name of a constant, Bazel repositories and packages map to nested
classes and non-alphanumeric characters are replaced by underscores. There are also special nested classes for the
current package, the current repository and the main repository.

| Bazel label                | Java constant                                   |
|----------------------------|-------------------------------------------------|
| `:foo`                     | `FooRunfiles.current_pkg.foo`                   |
| `:dir/some-File.txt`       | `FooRunfiles.current_pkg.dir_some_File_txt`     |
| `//path/to/pkg:foo`        | `FooRunfiles.current_repo.path.to.pkg.foo`      |
| `@foobar//path/to/pkg:foo` | `FooRunfiles.foobar.path.to.pkg.foo`            |
| `@//path/to/pkg:foo`       | `FooRunfiles.main_repo.path.to.pkg.foo`         |

The fully-qualified names of these constants can be shortened with `import static` directives.

### Step 3: Using the Bazel runfiles libraries

**C++**:
No additional dependency or include is needed to access the Bazel C++ runfiles library.
See [its main header](https://github.com/bazelbuild/bazel/tree/master/tools/cpp/runfiles/runfiles_src.h) for usage instructions.

**Java**:
No additional dependency is needed to access the Bazel Java runfiles library.
See [its main source file](https://github.com/bazelbuild/bazel/tree/master/tools/java/runfiles/Runfiles.java) for usage instructions.

## Examples

* [cc_runfiles](tests/cc_runfiles)
* [java_runfiles](tests/java_runfiles)

rules_runfiles

rules_runfiles Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

rules_runfiles

rules_runfiles Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README