# `rules_patchelf`

> A Bazel ruleset for patching ELF binaries.

## Getting Started

Add the following to `MODULE.bazel`:

```py
bazel_dep(name="rules_patchelf", version="...")
```

Use `patchelf_unpack` to unpack the downloaded packages and patch the ELF interpreter path:

```py
patchelf_unpack(
    name = "patched",
    # `rules_distroless#apt` extension is *highly* recommended
    srcs = ["@debian-bookworm-qemu//:packages"],
    filters = [
        "usr/share/doc/**",       # No need to unpack documentation
        "lib64/ld-linux-*.so.?",  # Remove dangling symlink
    ],
)
```

Use `patchelf_launcher` to launch a binary from the unpacked directory:

```py
patchelf_launcher(
    name = "qemu-system-x86_64",
    srcs = [
        ":patched",
        "@rules_patchelf//patchelf/launcher/elf/interpreter/debian",
        "@rules_patchelf//patchelf/launcher/library/path/debian",
    ],
    env = {
        "TMPDIR": "./tmp",
    },
)
```

Run the binary:

```console
$ bazelisk run -- :qemu-system-x86_64 --version
QEMU emulator version 7.2.13 (Debian 1:7.2+dfsg-7+deb12u7)
Copyright (c) 2003-2022 Fabrice Bellard and the QEMU Project developers
```

## Release Registry

The project publishes the relevant files to GitLab releases for use when a version has not been added to the upstream [BCR][bcr].

This is often the case for pre-release versions.

Add the following to `.bazelrc`:

```
# `bzlmod` pre-release registries
common --registry https://bcr.bazel.build
common --registry=https://gitlab.arm.com/bazel/rules_patchelf/-/releases/v1.0.0-alpha.1/downloads
```

Then a GitLab release version can be used in `bazel_dep`.

## Hermeticity

The project uses `rules_python`. Enable `--@rules_python//python/config_settings:bootstrap_impl=script` to enable hermetic Python execution.

The project uses `patchelf`. Enable a hermetic C/C++ toolchain to build the `patchelf` binary. `hermetic_cc_toolchain` is one option.

Otherwise, the module is entirely hermetic.

[bcr]: https://registry.bazel.build/