Adin Ćebić

Exploring map_directory in Bazel 9

Sun, 13 Sep 2026 18:04:29 +0200

In the world of Bazel, we prefer to be explicit as much as possible and register actions ahead of time. In fact, this is not just a preference but a strongly enforced rule that enables all the good stuff Bazel gives us.

However, there is a world where a bit of dynamism is useful—or, in some cases, unavoidable.

Today I am exploring the little-known map_directory API that was introduced in Bazel 9.

Registering actions dynamically

Say we write a rule that generates a couple of files and then want to register a separate Bazel action for each of those files.

The Bazel API did not facilitate this use case before version 9. Sure, we could have resorted to all sorts of tricks and hacks, but there was no nice native way to register actions based on the contents of a generated directory.

This is where map_directory comes in. It allows part of action registration to be deferred until execution time, when the contents of an input directory are known.

map_directory in action

The example below demonstrates generating a couple of files and then copying them with separate actions:

def _copy_files(template_ctx, *, input_directories, output_directories, tools, **_kwargs):
    for src in input_directories["src"].children:
        out = template_ctx.declare_file(src.tree_relative_path, directory = output_directories["out"])
        # Here we register one action per file; Bazel executes the command later.
        # Each action depends only on its input file and the copy tool.
        template_ctx.run(
            executable = tools["copy"],
            inputs = [src],
            outputs = [out],
            arguments = [src.path, out.path],
        )

def _demo_impl(ctx):
    src = ctx.actions.declare_directory(ctx.label.name + "_input")
    out = ctx.actions.declare_directory(ctx.label.name + "_output")

    ctx.actions.run_shell(
        outputs = [src],
        arguments = [src.path],
        command = """
mkdir -p "$1/nested"
echo hello > "$1/a.txt"
echo world > "$1/nested/b.txt"
""",
    )

    copy = ctx.actions.declare_file(ctx.label.name + "_copy.sh")
    ctx.actions.write(copy, '#!/bin/sh\nexec /bin/cp "$@"\n', is_executable = True)

    ctx.actions.map_directory(
        input_directories = {"src": src},
        output_directories = {"out": out},
        tools = {"copy": copy},
        mnemonic = "CopyFile",
        implementation = _copy_files,
    )

    return [DefaultInfo(files = depset([out]))]

map_directory_demo = rule(implementation = _demo_impl)

Creating a target from this rule and building it produces an unremarkable result, but it demonstrates what is now possible with this API at our disposal.

The important part is that _copy_files does not run during the regular analysis phase. It runs later, once Bazel knows the contents of the src tree artifact. At that point, it can inspect its children and register an individual copy action for each file.

Conclusion

While still greatly limited, map_directory allows us to introduce some controlled dynamism into our Bazel builds and makes certain things possible that previously required considerably more creativity.

I am pretty sure there are far more interesting examples of this feature being used, so feel free to look around on Github.

Finally, as always, I suggest consulting the official docs, at least as a reference, as well as the GitHub discussion around dynamic dependencies.

Bazel, APFS Clones, and Disk Space

Sun, 06 Sep 2026 17:22:12 +0200

I was recently writing about the problem of disk space usage when building with Bazel due to its many caches. That led me to pay more attention to the work being done in this area, and I discovered that Bazel 9.3.0 is expected to make better use of copy-on-write cloning on macOS #30776 to avoid unnecessarily duplicating files between the disk cache and the output base.

On APFS, this essentially means copy-on-write: the cloned files initially share the same underlying data blocks, so they don’t immediately take up twice the physical disk space. If either copy is modified, the filesystem only needs to allocate storage for the changed blocks.

Using APFS clones from Swift

Naturally, I got interested in learning how this feature works, and it turns out to be pretty simple. There is a low-level API function, clonefile(...), which does exactly what you would expect: it creates a copy-on-write clone of a file.

If I were to wrap that function in Swift, here is roughly how I would do it. In production code, I would also provide better error handling:

func clone(from source: String, to destination: String) -> Bool {
    let source = source.cString(using: .utf8)
    let destination = destination.cString(using: .utf8)
    let result = clonefile(source, destination, 0)
    return result == 0
}

I recommend taking a look at its man page to learn more about it.

Conclusion

I wanted to share this because I feel like APFS cloning is not talked about enough. It’s a simple API backed by a pretty powerful filesystem feature, and I hope you find it handy someday.

How to Reduce Bazel Disk Space Usage Across Git Worktrees

Sun, 30 Aug 2026 18:59:22 +0200

Ever since the advent of coding agents, a lot of engineers have started utilizing Git worktrees and, by extension, multiple Bazel output bases. We all know the story: Bazel caches tend to take up a lot of disk space when working with large projects. Manual deletion and garbage collection can only take you so far.

Enter bb-clientd

bb-clientd is a daemon that runs on your machine and can act as a local remote cache and proxy for Bazel.

More importantly, it also implements Bazel’s Output Service protocol, introduced in Bazel 7.2. This allows bb_clientd to manage Bazel’s output tree through a virtual filesystem—FUSE on Linux and NFSv4 on macOS—and lazily materialize files when they are actually accessed.

Combined with its content-addressed local cache, this means that multiple Bazel output bases can reuse the same cached content instead of each storing their own copies of identical files. This is particularly useful when working with multiple Git worktrees.

Because bb-clientd already has a nice README, there is no point in me explaining the setup in detail. But here is an example .bazelrc configuration that I keep in my global .bazelrc so I can enable it when needed:

common:bb_clientd --disk_cache=
common:bb_clientd --remote_cache=unix:///Users/<user>/Library/Caches/bb_clientd/grpc
common:bb_clientd --remote_instance_name=local/projects
common:bb_clientd --remote_upload_local_results
common:bb_clientd --experimental_remote_output_service=unix:///Users/<user>/Library/Caches/bb_clientd/grpc
common:bb_clientd --experimental_remote_output_service_output_path_prefix=/Users/<user>/bb_clientd/outputs

This lets me use just the local cache with:

bazel build --config=bb_clientd //...

NOTE: If you’re using rules_swift, make sure to check out the swift.module_map_home_is_cwd feature if you’re not using the Xcode toolchain. It makes module-map generation and compilation assume that header paths are relative to the workspace root, which can be important when using a virtualized output tree.

Conclusion

This is one of those things that I don’t see discussed enough in the Bazel community, yet it can save gigabytes of disk space—especially if you’re regularly working across multiple worktrees.

Preventing Transitive Swift Imports with Bazel

Sun, 23 Aug 2026 21:27:01 +0200

Swift’s permissive nature when it comes to module dependencies has always annoyed me and made my life a bit harder than I expected. Of course, I’m talking about transitive module imports.

You know the situation: there is a ModuleA which is a dependency of ModuleB, and if you declare ModuleB as a dependency of ModuleC, ModuleC can import ModuleA even though it never declared ModuleA as its own direct dependency.

There are a lot of reasons why you might not want that, from making dependencies harder to visualize to enforcing a certain module structure, and so on.

Unfortunately, Swift itself does not provide a mechanism to enforce direct module dependencies—or at least I don’t know of one.

Layering check via rules_swift

One of the reasons I like working with Bazel is the flexibility it provides. One example of that is a feature in rules_swift called layering check, which prevents importing modules that aren’t declared as direct dependencies.

It was introduced a couple of months ago in #1780.

So, for example:

swift_library(
    name = "Bottom",
    srcs = ["Bottom.swift"],
    module_name = "Bottom",
)

swift_library(
    name = "Middle",
    srcs = ["Middle.swift"],
    module_name = "Middle",
    deps = [":Bottom"],
)

swift_library(
    name = "Top",
    srcs = ["Top.swift"],
    module_name = "Top",
    deps = [":Middle"],
)

Now let’s say Top.swift tries to do this:

import Middle
import Bottom

Even though Bottom is available transitively through Middle, Top never declared it as a direct dependency.

With the Swift layering check enabled, building it:

bazel build //:Top --features=swift.layering_check_swift

should fail with an error resembling:

Layering violation in //path/to/package:Top
  The following modules were imported, but they are not direct dependencies:

      Bottom

  Please add the correct 'deps' ...

And that’s exactly what I want.

To fix it, simply declare Bottom as a direct Bazel dependency:

swift_library(
    name = "Top",
    srcs = ["Top.swift"],
    module_name = "Top",
    deps = [
        ":Bottom",
        ":Middle",
    ],
)

Conclusion

This is one of those features I wish more people knew about and used. It gives you much tighter control over your dependency graph and makes it harder for accidental dependencies to get imported.

Profiling Starlark Memory Usage in Bazel

Sun, 16 Aug 2026 18:15:22 +0200

When using Bazel within a large monorepo, there comes a time when memory starts becoming a problem, and it is important to be aware of the available tools that can help with diagnosis. Fortunately, Bazel offers Starlark memory profiling, which we can utilize to see how much memory is being swallowed by the analysis phase.

Setting up

Surprisingly, it is a little tedious to set this up, but in the end, it is not that difficult either.

First, we need to download the allocation instrumenter JAR from Maven Central. Once that’s on disk, we can start Bazel in memory tracking mode like so:

bazel --host_jvm_args=-javaagent:/path/to/java-allocation-instrumenter-3.3.4.jar \
      --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
      build --nobuild //path/to/target

Here, we start Bazel with memory tracking enabled and pass --nobuild so that only analysis is performed, which is what we want to measure.

After analysis completes, make sure not to shut down the Bazel server because you’ll lose the gathered data.

Now, to produce a memory profile, we’ll use Bazel’s dump command:

bazel --host_jvm_args=-javaagent:/path/to/java-allocation-instrumenter-3.3.4.jar \
      --host_jvm_args=-DRULE_MEMORY_TRACKER=1 \
      dump --skylark_memory=memory_profile.gz

Notice how we repeat the startup flags:

--host_jvm_args=-javaagent:/path/to/java-allocation-instrumenter-3.3.4.jar
--host_jvm_args=-DRULE_MEMORY_TRACKER=1

Failing to do so will result in a Bazel server restart, and you’ll have to repeat the whole process from the beginning.

Dealing with gathered data

Now that you have memory_profile.gz, you need to make sense of it. The Bazel docs recommend using pprof to inspect the profile.

There doesn’t appear to be a pprof formula in the main Homebrew formula index, but installing it is straightforward if you already have Go:

go install github.com/google/pprof@latest

The binary is installed into $GOPATH/bin, which is $HOME/go/bin by default.

Once installed, a useful starting point is a flame graph:

pprof -flame memory_profile.gz

or a text report annotated with source lines:

pprof -text -lines memory_profile.gz

Conclusion

Most Bazel users won’t ever need to gather a memory profile, but I believe it is good to be aware that this exists so you can reach for it when needed. Rule authors should be especially aware of it, as it is not that difficult to make a coding mistake in a rule that results in huge memory usage.

You can find more information about optimizing performance in the official Bazel docs.

Testing Bazel Remote Build Execution Locally with actiond

Sun, 09 Aug 2026 18:50:43 +0200

When configuring remote build execution, it is very important to test changes locally so you don’t waste time on CI. A lot of the time, people don’t even have access to an RBE environment. Yes, BuildBuddy offers their service for free for open-source projects, but I feel like having access to an RBE environment locally is invaluable.

I only recently started utilizing RBE more seriously, and while working through that setup I accidentally discovered actiond. I really wish I had known about it earlier. Having a remote executor that you can run locally makes experimenting with RBE, debugging issues, and checking whether your targets actually execute remotely much easier.

actiond from hermeticbuild

actiond is a full-fledged remote build executor that you can spin up easily simply by downloading it:

curl -L \
  https://github.com/hermeticbuild/actiond/releases/latest/download/darwin-actiond_macos_arm64 \
  -o darwin-actiond_macos_arm64
curl -L \
  https://github.com/hermeticbuild/actiond/releases/latest/download/SHA256.txt \
  -o SHA256.txt
grep ' darwin-actiond_macos_arm64$' SHA256.txt | shasum -a 256 -c -
chmod +x darwin-actiond_macos_arm64

And then just run it:

./darwin-actiond_macos_arm64 serve-vm \
  --listen=127.0.0.1:8980 \
  --root="$HOME/Library/Caches/actiond/vm"

NOTE: I assume you’re running on macOS.

Pointing Bazel at it

It is a matter of setting a few flags, which is best done in .bazelrc, as I can’t imagine anyone manually passing them every time:

build:local_rbe --remote_executor=grpc://127.0.0.1:8980
build:local_rbe --remote_cache=grpc://127.0.0.1:8980
build:local_rbe --platforms=//:linux_x86_64
build:local_rbe --extra_execution_platforms=//:linux_x86_64
build:local_rbe --spawn_strategy=remote
build:local_rbe --genrule_strategy=remote
build:local_rbe --remote_local_fallback=false
build:local_rbe --remote_upload_local_results=false
build:local_rbe --noremote_cache_compression

Then build with bazel build --config=local_rbe //....

Conclusion

This is an incredibly easy way to test whether all your targets build remotely, either when preparing to use a real RBE service or as a rule author wanting to ensure that your rules are fully hermetic and can execute remotely.

I wish I had found actiond earlier, because it removes a lot of the friction from experimenting with RBE locally and makes it much easier to catch remote-execution problems before they reach CI.

Less Boilerplate for Bazel Transitions

Sun, 02 Aug 2026 18:41:58 +0200

I’ve written about Bazel transitions multiple times: first when demonstrating rule extensions, and then when explaining split transitions.

Now I want to showcase a community-built way to apply transitions more easily.

Enter with_cfg.bzl

with_cfg.bzl is a convenient way to apply Bazel transitions. It was created by well-known community member Fabian, and I can’t recommend it enough.

Applying a transition to a plain swift_library

Say we want to ensure that our swift_library is always built with --compilation_mode=opt. We can achieve that quite easily with the following .bzl file:

load("@rules_swift//swift:swift_library.bzl", "swift_library")
load("@with_cfg.bzl", "with_cfg")

opt_swift_library, _opt_swift_library_internal = (
    with_cfg(swift_library)
        .set("compilation_mode", "opt")
        .build()
)

That’s it.

NOTE: You can ignore _opt_swift_library_internal. It needs to be assigned to a global variable because of Bazel’s restrictions on rule definitions, but you aren’t supposed to use it directly. Instead, use the generated opt_swift_library macro.

Finally, load opt_swift_library from the .bzl file containing the code above and use it just like a regular swift_library. The target and all its transitive dependencies will be built with the opt compilation mode.

Prior art

I won’t go into detail about what this would look like without with_cfg.bzl, as that’s already covered in my earlier articles.

Conclusion

Unfortunately, I discovered this way too late, but I’m glad it exists. It makes transitions much less tedious to write and reason about.

Pruning Unused Action Inputs in Bazel

Sun, 26 Jul 2026 17:53:04 +0200

Bazel has grown significantly since its initial open-source release, and it is hard to keep up with every release. One useful feature that may have slipped past you is unused_inputs_list, a parameter of ctx.actions.run(...) that lets an action report which of its declared inputs it did not actually use.

After the action executes successfully, Bazel can prune those files from the action’s effective input set. On subsequent incremental builds, changing only one of the reported unused files will not cause the action to run again.

This is post-execution dependency pruning, not pre-execution input discovery. The action still starts with all of its declared inputs. It reports unused inputs only after it has run. If the action later needs to execute again, Bazel restores the original input set first, because a previously unused input may be needed during the new execution.

A natural use case would be a compiler-like rule that begins with a conservative list of possible headers or source files, but can determine which ones it actually read.

A simple example

To demonstrate the unused_inputs_list parameter on ctx.actions.run(...), I came up with a deliberately contrived example that:

Receives choice.txt through a selector attribute.
Reads the contents of choice.txt.
Selects one file from srcs.
Copies the selected file to the output.
Reports every unselected source file as unused.

It is an extremely unrealistic rule, but I believe it demonstrates the idea clearly.

The select_one rule

Given the following select_one rule:

def _select_one_impl(ctx):
    output = ctx.actions.declare_file(ctx.label.name + ".out")
    unused_inputs = ctx.actions.declare_file(
        ctx.label.name + ".unused_inputs",
    )

    args = ctx.actions.args()
    args.add(ctx.file.selector)
    args.add(output)
    args.add(unused_inputs)
    args.add_all(ctx.files.srcs)

    ctx.actions.run(
        executable = ctx.executable._tool,
        arguments = [args],
        inputs = [ctx.file.selector] + ctx.files.srcs,
        outputs = [
            output,
            unused_inputs,
        ],
        unused_inputs_list = unused_inputs,
        mnemonic = "SelectOne",
    )

    return [
        DefaultInfo(files = depset([output])),
    ]

select_one = rule(
    implementation = _select_one_impl,
    attrs = {
        "selector": attr.label(
            mandatory = True,
            allow_single_file = True,
        ),
        "srcs": attr.label_list(
            mandatory = True,
            allow_files = True,
        ),
        "_tool": attr.label(
            default = Label("//:selector_tool"),
            executable = True,
            cfg = "exec",
        ),
    },
)

The unused_inputs file is still an ordinary declared output: it must appear in the action’s outputs list, and the tool must create it.

Passing that same File through unused_inputs_list gives the output additional meaning. It tells Bazel to read the file after execution and interpret its contents as a list of inputs that can be pruned.

The tool itself

Here is the small Swift program that reads the selector, copies the selected file, and reports the remaining candidates as unused:

import Foundation

func run() throws {
    let arguments = Array(CommandLine.arguments.dropFirst())
    let selectorPath = arguments[0]
    let outputPath = arguments[1]
    let unusedInputsListPath = arguments[2]
    let candidates = Array(arguments.dropFirst(3))

    let selectedName = try String(contentsOfFile: selectorPath, encoding: .utf8)
        .trimmingCharacters(in: .whitespacesAndNewlines)
    let selectedPath = candidates.first(where: {
        URL(fileURLWithPath: $0).lastPathComponent == selectedName
    })!

    let selectedContents = try Data(
        contentsOf: URL(fileURLWithPath: selectedPath)
    )
    try selectedContents.write(
        to: URL(fileURLWithPath: outputPath)
    )

    let unusedPaths = candidates.filter { $0 != selectedPath }
    let unusedContents =
        unusedPaths.isEmpty
        ? ""
        : unusedPaths.joined(separator: "\n") + "\n"

    try Data(unusedContents.utf8).write(
        to: URL(fileURLWithPath: unusedInputsListPath)
    )
}

try run()

The unused-input file contains one input path per line. These need to be the action’s execution paths, not merely arbitrary workspace-relative names. Bazel reads each line and matches it against the mapped execution paths of the action’s inputs.

The example avoids having to reconstruct those paths by writing the exact candidate strings that Bazel passed to the tool.

The selected file must not appear in the unused-input list because its contents were copied to the output. The selector must not appear there either because changing choice.txt may change which source file is selected.

Putting it all together

Here is the final BUILD.bazel file:

load("@rules_swift//swift:swift_binary.bzl", "swift_binary")
load(":select_one.bzl", "select_one")

swift_binary(
    name = "selector_tool",
    srcs = ["main.swift"],
)

select_one(
    name = "demo",
    selector = "choice.txt",
    srcs = [
        "a.txt",
        "b.txt",
    ],
)

Suppose the files contain:

# choice.txt
a.txt

# a.txt
Contents of A

# b.txt
Contents of B

On the first build, the action receives all three declared inputs:

bazel build //:demo

The tool selects a.txt, writes its contents to demo.out, and writes the path of b.txt to demo.unused_inputs.

At that point, Bazel knows that b.txt did not contribute to this execution. Modifying only b.txt will therefore not cause the SelectOne action to execute again during a subsequent incremental build:

Changing a.txt, on the other hand, must rerun the action because a.txt produced the output.

Changing choice.txt must also rerun it. When that happens, Bazel restores the complete original input set before executing the action. The tool can then select b.txt, even though b.txt was reported as unused during the previous execution.

Conclusion

I have not seen many rulesets use unused_inputs_list directly, but it is worth knowing that it exists. It is most useful for actions that must declare a conservative set of possible inputs but can reliably determine which subset mattered after execution.

I enjoy exploring the more obscure corners of Bazel from time to time, since I tend to find features I did not know I needed.

A Note on Bazel’s config.exec()

Sun, 19 Jul 2026 17:22:27 +0200

When writing a rule that executes in the exec configuration, we need to communicate that to Bazel so it doesn’t attempt to build it for the target configuration:

generator = rule(
    implementation = _generator_impl,
    ...,
    cfg = "exec",
)

While there is nothing wrong with cfg = "exec", my opinion is that we should use the newer transition object API.

This means that instead of:

cfg = "exec"

we use:

cfg = config.exec()

Why?

Apart from legitimate use cases such as transition composition and passing an exec group, I think using the object form is better for readability and discoverability.

"exec" is a special string. You need to already know what it means and where it is supported.

config.exec(), on the other hand, looks like an API. It is easier to discover, easier to search for, and makes it clearer that we are applying an execution transition.

Passing the "exec" string is not deprecated, and I am not suggesting that it is incorrect.

Conclusion

This is simply my take on config.exec().

Migrating an entire codebase from cfg = "exec" to cfg = config.exec() will not result in any build-time improvement. It will, however, make the API usage slightly more explicit and leave room for features that the string form cannot express.

Making Bazel Module Extensions Work Together with override_repo

Sun, 12 Jul 2026 14:59:39 +0200

Recently, I have noticed more rulesets adopting Bzlmod-specific features. With Bazel 6 no longer supported and Bzlmod adoption continuing across the ecosystem, rulesets can increasingly rely on newer module APIs.

One feature that caught my attention while I was setting up a hermetic Android toolchain is the ability to override a repository generated by a module extension.

override_repo requires Bazel 7.4.0 or newer and can only be used by the root module.

Overriding a repository

There are several reasons to override a repository generated by a module extension.

It can simplify migrations by allowing existing call sites to keep using the same repository name. It can also avoid introducing multiple similarly named repositories. Most importantly, it gives module authors a way to provide a smoother developer experience when integrating with other rulesets.

A good example is Keith’s hermetic Android toolchain. Setting it up requires only a small amount of configuration:

bazel_dep(
    name = "hermetic_android_toolchains",
    version = "0.3.0",
)
bazel_dep(
    name = "rules_android",
    version = "0.7.3",
)

android = use_extension(
    "@hermetic_android_toolchains//:extensions.bzl",
    "android",
)
android.sdk(
    build_tools_version = "37.0.0",
    version = "37.0",
)
use_repo(android, "androidsdk")

# Make @rules_android's @androidsdk labels resolve to the hermetic SDK.
rules_android_sdk = use_extension(
    "@rules_android//rules/android_sdk_repository:rule.bzl",
    "android_sdk_repository_extension",
)
override_repo(rules_android_sdk, "androidsdk")

register_toolchains("@androidsdk//:all")

The important line is:

override_repo(rules_android_sdk, "androidsdk")

The rules_android_sdk extension normally generates its own repository named androidsdk. The positional form of override_repo tells Bazel to replace it with the repository of the same name that is already visible to the root module—in this case, the androidsdk repository generated by hermetic_android_toolchains.

As a result, references to @androidsdk from the rules_android extension resolve to the hermetically downloaded SDK rather than a separately configured Android SDK repository.

The keyword form can be used when the two repositories have different names:

override_repo(
    some_extension,
    generated_repo_name = "replacement_repo_name",
)

Here, generated_repo_name is the repository produced by the extension, while replacement_repo_name is a repository visible to the root module.

Conclusion

That is all there is to it. override_repo is a small Bzlmod feature, but it can make integrations and migrations considerably cleaner. It is worth keeping in mind whenever two module extensions need to agree on the repository behind a well-known name.

Stamping iOS Builds with Bazel

Sun, 05 Jul 2026 19:05:10 +0200

Stamping is the act of embedding build metadata into the product that we ship to customers. It can help with issue diagnosis, analytics, and so on. Conveniently, Bazel offers us a first-class solution, and it is very easy to take advantage of it in the context of iOS apps.

Workspace status script

The first step in enabling stamping is to create a workspace status script. For example, we can create a script that emits the current Git commit hash:

#!/usr/bin/env bash

set -eu -o pipefail

echo "STABLE_GIT_COMMIT $(git rev-parse HEAD)"

Now we need to tell Bazel to execute the script:

--workspace_status_command=./tools/workspace_status.sh

Reading the value at build time

For iOS apps, or really any Apple platform app, it is usually best to embed this data in a plist file so we can read it at runtime. First, we use a genrule to read the workspace status data and materialize a plist file:

genrule(
    name = "commit_plist",
    outs = ["Commit.plist"],
    cmd = """
commit="$$(sed -n 's/^STABLE_GIT_COMMIT //p' bazel-out/stable-status.txt)"
plutil -convert xml1 -o "$@" - <<EOF
{
    "GIT_COMMIT": "$${commit}"
}
EOF
""",
    stamp = True,
)

From there, it is just a matter of adding this target to the infoplists attribute of any Apple platform application target, like ios_application. Because rules_apple performs plist merging, this value will end up in the final Info.plist file that we ship in the app bundle.

A word on the `stamp` attribute

Notice the stamp = True attribute on the genrule? That is what allows the genrule action to access bazel-out/stable-status.txt and bazel-out/volatile-status.txt.

Without it, the action should not rely on those files being present. In this example, the important part is stamping the genrule that materializes the plist.

This is separate from the stamp attribute you may see on Apple rules like ios_application, where stamping controls whether build information is encoded into the binary. For this plist-based approach, we do not need to rely on link stamping at the application target level.

Reading the value at runtime

Because the value ends up in Info.plist, we can read it at runtime through the Bundle / NSBundle API.

Conclusion

There you have it: an easy way to stamp iOS builds. I hope it helps you discover and fix bugs in production more easily.

Making Developer Tools Available Through Bazel

Sun, 28 Jun 2026 18:51:25 +0200

Traditionally, when setting up a developer machine, instructions include something like “install the following tools using Homebrew”. What if we could always have tools available without asking developers to install anything but Bazel?

This is easily achievable with Bazel since it gives us a way to download and execute binaries. Before diving into the implementation, let’s first explore the downsides of asking developers to install tools on their own.

Problems with Homebrew for developer tools

brew install …

When developing on macOS, the “default” package manager is Homebrew, so we install tools like linters and formatters using it. However, it is not great for versioning in this use case. By default, we usually end up installing whatever version Homebrew currently resolves, unless we specifically do extra work to avoid that.

This is the first problem: we can’t expect people to ensure that they have exactly the same version of a tool as everybody else, especially if the organization is large.

Distributing tools

Just like we can’t easily enforce versions, we also can’t easily enforce tool replacement. Say that we built an internal linter and we want everybody to use it. What is the distribution mechanism? Perhaps an internal Brew formula? It works, but it is tedious to set up and maintain.

Using Bazel and rules_multitool

There have been a couple of community posts about rules_multitool, and I want to give my take on it.

How it works

This ruleset provides a convenient way to tell Bazel to download a binary and expose it as a target under the @multitool//tools/{TOOL_NAME} label. It takes in multitool.lock.json files and uses information from the lockfile to invoke Bazel repository rules, download the specified binary, and expose it as a runnable tool.

Setting it up

Declare the dependency in MODULE.bazel as described here.
Call its module extension from MODULE.bazel:

multitool = use_extension("@rules_multitool//multitool:extension.bzl", "multitool")
multitool.hub(lockfile = "//tools:multitool.lock.json")
use_repo(multitool, "multitool")

Of course, you can put your multitool.lock.json wherever you like. I tend to keep it under the tools/ package.

Add multitool.lock.json and give it some tools to work with, e.g.:

{
    "$schema": "https://raw.githubusercontent.com/theoremlp/rules_multitool/main/lockfile.schema.json",
    "bb": {
        "binaries": [
            {
                "kind": "file",
                "url": "https://github.com/buildbuddy-io/bazel/releases/download/5.0.350/bazel-5.0.350-linux-x86_64",
                "sha256": "d14e6a240dc5e8bc3ebb625ff7c139ba8e380f1440f9e2f60e9c1d7850d012c9",
                "os": "linux",
                "cpu": "x86_64"
            },
            {
                "kind": "file",
                "url": "https://github.com/buildbuddy-io/bazel/releases/download/5.0.350/bazel-5.0.350-darwin-arm64",
                "sha256": "f16cc54449eb62ee65ac7ec3b45d7bce7922225a3c004925cbb25982faa8a9cd",
                "os": "macos",
                "cpu": "arm64"
            }
        ]
    },
    "yq": {
        "binaries": [
            {
                "kind": "file",
                "url": "https://github.com/mikefarah/yq/releases/download/v4.52.4/yq_linux_arm64",
                "sha256": "4c2cc022a129be5cc1187959bb4b09bebc7fb543c5837b93001c68f97ce39a5d",
                "os": "linux",
                "cpu": "arm64"
            },
            {
                "kind": "file",
                "url": "https://github.com/mikefarah/yq/releases/download/v4.52.4/yq_linux_amd64",
                "sha256": "0c4d965ea944b64b8fddaf7f27779ee3034e5693263786506ccd1c120f184e8c",
                "os": "linux",
                "cpu": "x86_64"
            },
            {
                "kind": "file",
                "url": "https://github.com/mikefarah/yq/releases/download/v4.52.4/yq_darwin_arm64",
                "sha256": "6bfa43a439936644d63c70308832390c8838290d064970eaada216219c218a13",
                "os": "macos",
                "cpu": "arm64"
            }
        ]
    }
}

This is it. You can now execute bazel run @multitool//tools/yq or bazel run @multitool//tools/bb, and Bazel will download and execute them just fine.

Making it more convenient

Typing out the label from above will quickly get tedious. What if we could instead run the yq tool as easily as ./tools/yq?

To achieve that, we could do the following trick:

Create a script at tools/_run_tool.sh with the following content:

#!/usr/bin/env bash

target="@multitool//tools/$(basename "$0")"

bazel run \
    --run_in_cwd \
    --noshow_progress \
    --show_result=0 \
    --ui_event_filters=-info \
    "$target" -- "$@"

Create a symlink for every tool with its name, e.g. a yq symlink that links to tools/_run_tool.sh.

That will expand $(basename "$0") in tools/_run_tool.sh to the name of the symlink and allow you to execute ./tools/yq. Or, if you put the symlink at the root, it gets even more convenient: ./yq.

Conclusion

I think the trick with symlinks is quite powerful, and you don’t really have to use rules_multitool if you don’t want to. The same idea can work with any Bazel target that exposes a runnable tool.

Overall, I like this setup very much because it requires almost nothing from developers. They can just use the tools provided to them while not even thinking about versions.

Avoiding .DS_Store Cache Misses in Bazel

Sun, 21 Jun 2026 18:42:25 +0200

It is well known that macOS Finder .DS_Store files should never be checked in to a repo, or leave the single machine for that matter.

Fairly recently, I noticed that a lot of my iOS resource processing actions were missing the cache for seemingly no reason. That is, until I looked at the Bazel action inputs. There, I noticed that every action that missed the cache had an extra input. Of course, it was the .DS_Store file.

The problem

The problem popped up because of the act of balancing developer convenience and build correctness. Given the following glob pattern:

resources = glob(["Assets.xcassets/**"]),

we allow engineers to freely add or remove files in an iOS asset catalog without needing to constantly modify the list in the BUILD.bazel file.

This, of course, means that .DS_Store files can get picked up if the engineer ever opened a Finder window at the given path. One might say that rules_apple should take care of this. However, that’s easier said than done, since asset catalogs can host many different resource types. Plus, Apple might extend the list of accepted resources at any time, which would require a rules_apple release just to add a file extension to some list.

The solution

The solution to this problem is quite simple: just make a macro for the glob() function:

def safe_glob(include, **kwargs):
    exclude_pattern = kwargs.pop("exclude", []) + ["**/.DS_Store"]
    return native.glob(
        include = include,
        exclude = exclude_pattern,
        **kwargs
    )

Now just load this symbol and use it instead of plain glob(...).

Conclusion

A neat trick to get around the fact that neither .bazelignore nor REPO.bazel solve this problem. I bet similar annoying files exist on Linux as well as Windows.

External Repo File Checks In Bazel 9

Sun, 14 Jun 2026 16:42:34 +0200

In a quest to speed up Bazel builds we tend to pick every available low-hanging fruit once somebody discovers it. One of those used to be telling Bazel not to check external repos for file changes, since that can take a while in a dependency-heavy repo.

Prior Art

Historically we used --noexperimental_check_external_repository_files to skip checks for files in external repositories. That flag still exists in Bazel (source), and bazelrc-preset.bzl still sets it (source).

Bazel 9 gained the repo contents cache via --repo_contents_cache. Cacheable external repos can now be served out of that cache.

That matters because Bazel does not treat repo-contents-cache-backed files as the old EXTERNAL_REPO case. In the source they are tracked as EXTERNAL_OTHER instead. Bazel 9 also added --experimental_check_external_other_files to control checks for those paths..

Conclusion

If you have repo contents cache enabled and your goal is the old “don’t spend time stat’ing external repos on no-op builds” behavior, you likely want both:

--noexperimental_check_external_repository_files
--experimental_check_external_other_files=false

The old flag still matters for repos that are not served out of the repo contents cache. The new flag matters for cache-backed repos.

If repo contents cache is disabled, --experimental_check_external_other_files=false can still help with those broader EXTERNAL_OTHER checks, but it does not replace the old external-repository flag.

Cleaning up old Bazel patterns

Sun, 07 Jun 2026 21:41:28 +0200

From time to time, it is worth cleaning up old Bazel stuff in your repositories. This is especially useful before a major Bazel upgrade, because it reduces the amount of migration noise you need to deal with. Most of these cleanups are not difficult, but they make the codebase a little easier to deal with.

The suggestions below are relevant if you are on Bazel 8.1.0 or newer.

Sets

Starting with Bazel 8.1, Starlark has native support for sets, which removes the need to use sets from bazel_skylib.

So instead of:

sets.make([1, 2, 3])

you can write:

set([1, 2, 3])

Native sets support the usual set algebra, such as union, intersection, difference, and symmetric difference, so this should cover most use cases where you previously reached for bazel_skylib.

Remove function_transition_allowlist when creating transitions

The conventional wisdom used to be that you needed to create a private _allowlist_function_transition attribute for Starlark transitions to work.

That is no longer necessary in modern Bazel versions, so you can remove:

"_allowlist_function_transition": attr.label(
    default = "@bazel_tools//tools/allowlists/function_transition_allowlist",
),

repo_name is usually no longer worth keeping

Historically, many repositories used reverse-DNS-style names for external dependencies because that was the common WORKSPACE convention. With Bzlmod, the module name is usually the better default.

For example:

bazel_dep(name = "rules_swift", version = "3.6.1", repo_name = "build_bazel_rules_swift")

can become:

bazel_dep(name = "rules_swift", version = "3.6.1")

This makes labels and load statements shorter and easier to write by hand.

Just make sure you update any remaining references to the old apparent repository name, such as @build_bazel_rules_swift, before removing repo_name.

Start using `REPO.bazel`

I already wrote about this in my article about dropping .bazelignore and in suppressing warnings in external Swift repositories, so I encourage reading those if you want more details.

The short version is that REPO.bazel gives you a better place to express repository-wide behavior. It marks a repository boundary and lets you set repository-level attributes in a way that fits better with modern Bazel.

`compatibility_level` is a no-op

If you are a rules author, do not spend time tuning compatibility_level. Starting with Bazel 8.6.0 and 9.1.0, both compatibility_level and max_compatibility_level are no-ops.

This makes me extremely happy because this thing often created more pain for users than it solved. If you introduce a breaking change, it is better to provide clear error messages and an actionable migration path instead of relying on Bazel module version selection to protect users.

A word about flags

In every major Bazel version, there are flags that get removed, become no-ops, or get flipped.

I do not recommend tracking all of that manually. There is a good chance you will miss something, or sometimes get it wrong. The better approach is to use bazelrc-preset.bzl, which applies version-appropriate flags for the Bazel version you are using.

Conclusion

There is probably more cleanup work that I am missing. However, these are low-hanging improvements that are usually easy to apply and easy to review.

Running Multiple Bazel Targets in a Single Invocation

Sun, 31 May 2026 17:44:36 +0200

There are many instances where it would be really convenient to run multiple targets at once. By default, Bazel will not execute all targets even if you pass multiple ones:

bazel run //:lint //:format

In this case, only one of them would be executed.

Enter rules_multirun

rules_multirun is a set of rules that helps with running multiple targets either sequentially or in parallel. It is developed and maintained by Keith Smiley.

Running multiple targets

It is extremely easy to get started. First, load the multirun rule and use it like this:

load("@rules_multirun//:defs.bzl", "multirun")

multirun(
    name = "xcodeproj",
    testonly = True,
    commands = ["//apps/app1:xcodeproj", "//apps/app2:xcodeproj"],
    jobs = 0,
)

Here, I used the multirun rule to create a single runnable target that generates Xcode projects for two of my apps:

bazel run //:xcodeproj

Execution modes

The jobs attribute specifies whether targets should run sequentially or in parallel. The default value is 1, which means that targets will run one after the other. In the example above, I explicitly set it to 0 to make sure both Xcode projects are generated in parallel.

This is something that needs to be decided on a case-by-case basis, since parallel execution might not be a good fit for tools that modify files.

Why testonly

This is typically not required, but given the specifics of rules_xcodeproj and my project setup, I need to pass it in this scenario.

That is because xcodeproj passes testonly = True as soon as you add test targets, and it does that to satisfy Bazel’s restriction that non-test targets cannot depend on test-only targets.

So, like I said, this is typically not needed, but you might run into it, so I figured it was worth explaining.

Other rules from rules_multirun

rules_multirun is a set of rules, not just the multirun rule. There is a rule for configuring individual targets and commands, rules for executing targets with transitions, and more.

It is best to consult the rules_multirun docs on GitHub for the full list of available options.

Conclusion

This is a ruleset that I find extremely convenient in my daily work, and I tend to strive to optimize that last mile of developer experience whenever I can.

One thing I intentionally changed: your intro said Bazel executes only the “first” target, but then the example said only format runs. I made it “only one of them” to avoid the contradiction.

Suppressing Warnings in External Swift Dependencies with Bazel

Sun, 24 May 2026 17:35:00 +0200

It’s very common to want to apply some Bazel feature only to your first-party repo while omitting external dependencies.

A common case in the Swift world is suppressing warnings for external dependencies brought in by rules_swift_package_manager, since we usually can’t do much about third-party code. There are countless other examples too, like treating warnings as errors for our own code while avoiding that for third-party deps.

REPO.bazel to the rescue

I wrote about REPO.bazel in an earlier article, where I explained how to replace .bazelignore with glob semantics.

For the use cases described in the intro of this article, REPO.bazel is extremely useful. It lets us apply Bazel features, which I’ve also written about before, only to our own repo.

Suppressing warnings in external Swift libraries

To achieve this, we need to do two things.

First, suppress warnings globally in .bazelrc:

# Suppress Swift warnings
common                --features=swift.suppress_warnings
common                --host_features=swift.suppress_warnings

# Suppress clang warnings
common                --features=suppress_warnings
common                --host_features=suppress_warnings

Then, disable those features for our first-party repo using the repo(...) function in REPO.bazel. The repo(...) function accepts the same arguments as package(...):

repo(
    features = [
        "-swift.suppress_warnings",
        "-suppress_warnings",
    ],
)

Conclusion

And that’s really it. A neat trick to have in your toolbox.

I also want to make it clear that I wasn’t aware of this trick until a fellow Apple rules maintainer, Aaron Sky, shared it in the Bazel Slack workspace.

Hot Reloading a Bazel-Based iOS App with InjectionNext

Sun, 17 May 2026 21:25:55 +0200

When working on a medium to large iOS app, it can be daunting to constantly rebuild and manually go through app screens just to test your changes. Yes, Xcode previews exist, but in my experience, they can be slow on larger projects. They also require real code in the preview setup, which can be tricky to get right if you use dependency injection, since the code that registers all the dependencies probably will not run, often leading to crashes.

Enter InjectionNext

InjectionNext is an app that uses the -interposable linker feature to dynamically swap classes so that changes are reflected without rebuilding the app.

To set it up in a Bazel-based iOS project, I recommend the following:

Integrate the InjectionNext Swift package using rules_swift_package_manager.
Make sure to set the -interposable linker flag in debug mode only on your ios_application target:

linkopts = select({
    # InjectionNext hot reload needs debug app symbols to stay
    # interposable so injected dylibs can rebind calls to replacement
    # implementations instead of always hitting the original image.
    "//:debug": ["-interposable"],
    "//conditions:default": [],
}),

Similar to the linker flag, make sure that InjectionNext is linked to your app only in debug mode on the ios_application target:

deps = [":App.library"] + select({
    "//:debug": ["@swiftpkg_injectionnext//:InjectionNext"],
    "//conditions:default": [],
}),

Finally, you need the InjectionNext macOS app. Launch it, then click the option to launch Xcode from there.

NOTE: Please use the version I linked above or newer, because this is the version where my patch to make it work with rules_xcodeproj landed.

Further Source Changes Needed

Unfortunately, this is still not enough. To make everything work, you need to add @objc func injected() to every UIKit view or view controller where you call functions like setNeedsLayout() and layoutIfNeeded().

Of course, doing that manually for every view is tedious. The solution is either to integrate Inject, a Swift package that does this for you and also handles SwiftUI, or to write your own Swift macro, such as @HotReloadable, which you apply to the relevant types and which generates this code for you in debug mode.

Conclusion

I know this can seem like a lot of work, but I firmly believe that it quickly starts paying dividends as soon as you start iterating on your app, since it saves so much time.

NOTE: To make the integration with rules_swift_package_manager work, you need a release that includes my fix for collecting .s files.

A Practical Introduction to Bazel Persistent Workers

Sun, 10 May 2026 18:45:12 +0200

Typically, Bazel rules execute actions that usually correspond to tool processes on the host OS. Sometimes this behavior can incur startup costs, like bootstrapping a JVM or initializing a compiler. To work around that, Bazel has the concept of persistent workers.

A persistent worker is essentially a long-lived process that accepts work requests and responds with work responses. Imagine a process that keeps a compiler alive and dispatches sources to compile without paying the startup cost every time.

Creating a rule that leverages workers

Because this is a fairly advanced concept in Bazel, and usually only rule authors deal with it, I tried to come up with a simple example that demonstrates it.

An uppercase rule

We will write a rule that simply uppercases the text in a given file. To begin, we need to meet a few requirements. The first one is adding dependencies in our MODULE.bazel:

bazel_dep(name = "swift_argument_parser", version = "1.7.1")
bazel_dep(name = "rules_swift", version = "3.6.1")

These will come into play a bit later.

Creating a rule

Like I said, this is a simple rule, but the code may look a bit scary at first. Create uppercase.bzl at the root of the directory:

def _uppercase_impl(ctx):
    out = ctx.actions.declare_file(ctx.label.name + ".out")
    args_file = ctx.actions.declare_file(ctx.label.name + ".worker_args")

    # These are the per-action arguments. Bazel will send these to the
    # persistent worker inside each WorkRequest.
    ctx.actions.write(
        output = args_file,
        content = "\n".join([
            "--input=" + ctx.file.src.path,
            "--output=" + out.path,
        ]),
    )

    ctx.actions.run(
        executable = ctx.executable._worker,
        inputs = [
            ctx.file.src,
            args_file,
        ],
        outputs = [out],
        arguments = [
            # For worker actions, the last argument is special:
            # it must be an @flagfile containing the per-request args.
            "@" + args_file.path,
        ],
        mnemonic = "UppercaseWorker",
        execution_requirements = {
            "supports-workers": "1",
            "requires-worker-protocol": "json",
        },
    )

    return [DefaultInfo(files = depset([out]))]


uppercase = rule(
    implementation = _uppercase_impl,
    attrs = {
        "src": attr.label(
            allow_single_file = True,
            mandatory = True,
        ),
        "_worker": attr.label(
            default = "//tools:worker",
            executable = True,
            cfg = "exec",
        ),
    },
)

The important part here is the arguments list. For worker actions, Bazel treats the last argument specially when it is an @flagfile. The contents of that file become the per-request arguments inside the WorkRequest. Any arguments before that are considered startup arguments for the worker process.

Now that the rule is in place, we need to create the actual worker binary. Because Swift is my language of choice, we will write it using Swift, but you can implement it in any language.

The Swift worker

Typically, I would split this out into multiple Swift files, but for the sake of simplicity, I will shove everything into one Swift file called worker.swift:

import Foundation
import ArgumentParser

struct WorkRequest: Decodable {
    var arguments: [String]?
    var requestId: Int?

    // Bazel may send other fields such as inputs, verbosity, etc.
    // JSONDecoder ignores unknown fields by default, which is what we want.
}

struct WorkResponse: Encodable {
    var requestId: Int
    var exitCode: Int
    var output: String
}

struct UppercaseArgs: ParsableArguments {
    @Option(name: .long)
    var input: String

    @Option(name: .long)
    var output: String
}

func expandArgs(_ args: [String]) throws -> [String] {
    var expanded: [String] = []

    for arg in args {
        if arg.hasPrefix("@") {
            let path = String(arg.dropFirst())
            let contents = try String(contentsOfFile: path, encoding: .utf8)

            for line in contents.split(separator: "\n") {
                let trimmed = line.trimmingCharacters(in: .whitespacesAndNewlines)

                if !trimmed.isEmpty {
                    expanded.append(trimmed)
                }
            }
        } else {
            expanded.append(arg)
        }
    }

    return expanded
}

func runOne(_ rawArgs: [String]) throws {
    let args = try UppercaseArgs.parse(expandArgs(rawArgs))

    let inputText = try String(contentsOfFile: args.input, encoding: .utf8)

    try inputText.uppercased().write(
        toFile: args.output,
        atomically: true,
        encoding: .utf8
    )
}

func writeResponse(requestId: Int, exitCode: Int = 0, output: String = "") {
    let response = WorkResponse(
        requestId: requestId,
        exitCode: exitCode,
        output: output
    )

    do {
        let data = try JSONEncoder().encode(response)

        FileHandle.standardOutput.write(data)
        FileHandle.standardOutput.write(Data("\n".utf8))
    } catch {
        // Important: do not print normal logs to stdout.
        // In worker mode, stdout is reserved for WorkResponse JSON.
        FileHandle.standardError.write(
            Data("failed to encode WorkResponse: \(error)\n".utf8)
        )
        exit(1)
    }
}

func persistentLoop() {
    let decoder = JSONDecoder()

    while let line = readLine() {
        do {
            let request = try decoder.decode(
                WorkRequest.self,
                from: Data(line.utf8)
            )

            let requestId = request.requestId ?? 0
            let arguments = request.arguments ?? []

            do {
                try runOne(arguments)
                writeResponse(requestId: requestId)
            } catch {
                writeResponse(
                    requestId: requestId,
                    exitCode: 1,
                    output: String(describing: error)
                )
            }
        } catch {
            writeResponse(
                requestId: 0,
                exitCode: 1,
                output: "failed to decode WorkRequest: \(error)"
            )
        }
    }
}

@main
struct Worker {
    static func main() {
        let startupArgs = Array(CommandLine.arguments.dropFirst())

        if startupArgs.contains("--persistent_worker") {
            persistentLoop()
        } else {
            // Non-worker fallback path. This lets the same executable still work
            // when Bazel uses local execution instead of worker execution.
            do {
                try runOne(startupArgs)
            } catch {
                FileHandle.standardError.write(Data("\(error)\n".utf8))
                exit(1)
            }
        }
    }
}

A persistent worker has a small protocol contract with Bazel: it should accept the --persistent_worker flag, read WorkRequests from stdin, and write WorkResponses to stdout. If the same binary is run without --persistent_worker, it should behave like a normal one-shot tool. This fallback path is useful because Bazel may still run the action without the worker strategy.

One small but important detail: in worker mode, stdout belongs to the worker protocol. If you need to log something, write it to stderr instead.

I will not get into every detail here. I do expect the reader to be familiar with Swift and the general concept of Bazel workers.

We are missing the actual Bazel target for the worker at tools/BUILD.bazel:

load("@rules_swift//swift:swift_binary.bzl", "swift_binary")

swift_binary(
    name = "worker",
    srcs = ["worker.swift"],
    visibility = ["//visibility:public"],
    deps = ["@swift_argument_parser//:ArgumentParser"],
)

Trying out the rule

At the root, it is time to create a BUILD.bazel, load our rule, and build it:

load("//:uppercase.bzl", "uppercase")

uppercase(
    name = "hello",
    src = "hello.txt",
)

hello.txt is just a text file that I created to demonstrate the rule.

Building and verifying

To try out our new rule, execute:

bazel build :hello --spawn_strategy=worker,sandboxed --worker_verbose

We set --spawn_strategy=worker,sandboxed to make sure that our rule runs using the worker strategy and falls back to the standard sandboxed strategy. The fallback is important because there are actions that run because of rules_swift that do not necessarily use workers.

--worker_verbose is here just to make it easier to see that our worker is being used.

The output should look something like this:

INFO: Analyzed target //:hello (102 packages loaded, 649 targets configured, 2 aspect applications).
INFO: Created new non-sandboxed singleplex SwiftCompile worker (id 5, key hash -1813863811), logging to /Users/adincebic/Library/Caches/bazel/_bazel_adincebic/19f2a862cd16d28bfab74de8ca294508/bazel-workers/worker-5-SwiftCompile.log
INFO: Created new non-sandboxed singleplex UppercaseWorker worker (id 6, key hash -755134554), logging to /Users/adincebic/Library/Caches/bazel/_bazel_adincebic/19f2a862cd16d28bfab74de8ca294508/bazel-workers/worker-6-UppercaseWorker.log
INFO: Found 1 target...
Target //:hello up-to-date:
  bazel-bin/hello.out
INFO: Elapsed time: 19.851s, Critical Path: 19.03s
INFO: 60 processes: 30 internal, 26 darwin-sandbox, 4 worker.
INFO: Build completed successfully, 60 total actions

To verify the result, inspect bazel-bin/hello.out. It should contain the uppercase version of hello.txt.

And that’s it.

A few notes

This is the simplest example I could come up with, and it comes with a few caveats:

My worker implementation does not implement cancellation.
This is a singleplex worker, meaning Bazel sends it one request at a time.
The parsing logic could be more robust.
The worker ignores fields like inputs and verbosity from WorkRequest, which is fine for this example but probably not what you would do in a production worker.

Conclusion

This is one of those advanced Bazel concepts that you do not run into often, even if you write your own rules, purely because it is not always needed. But if you ever need persistent workers, I hope this gets you started.

Why My Xcode Extension Kept Asking for File Permissions

Sun, 03 May 2026 21:41:59 +0200

Recently, I worked on developing an Xcode source editor extension that needed to run some of our internal code formatters. These formatters are driven by configuration files that define how the tools should be executed. Because Xcode extensions must be sandboxed, they can’t directly access arbitrary file locations, including these configuration files.

To work around this, we used a container app to prompt users to select the location of the configuration files. We then created security-scoped bookmarks and passed them to the extension process. As expected, the standard way to share data between processes—such as an app and its extension—is by using Apple’s App Groups capability.

After setting this up, I noticed that the extension kept prompting the user to grant access to the shared files, even though both the app and extension were part of the same app group. This was unexpected—intuitively, accessing files within your own shared container shouldn’t trigger permission prompts.

The mistake

Coming from an iOS background, I defined the app group ID like this:

<key>com.apple.security.application-groups</key>
<array>
	<string>group.example.app</string>
</array>

After running both the app and the extension and inspecting ~/Library/Group Containers/, it was clear that the shared container had been created. However, what I missed is that on macOS, App Group identifiers must be prefixed with the Team ID (for example, TEAMID.group.example.app). This allows the system to correctly associate the app group with your developer account and properly link the app and its extension.

Without this prefix, the container may still appear to exist, but entitlement validation and access behavior can be inconsistent—leading to issues like repeated permission prompts.

Conclusion

This turned out to be one of those frustrating issues where the root cause isn’t immediately obvious, even after checking open-source projects and documentation. To be fair, Apple does document this requirement—but it’s easy to overlook, especially since iOS does not require this detail and doesn’t expose the same behavior as clearly.

Centralizing Dependency Fetching in Bazel with the Remote Asset API

Sun, 26 Apr 2026 17:40:57 +0200

It has become increasingly common for major providers to experience outages—from Git servers being unavailable to failures when downloading external dependencies.

There are several ways to work around this, such as internal mirrors, vendoring dependencies, and similar approaches. While effective, these solutions can feel somewhat heavy-handed.

Bazel Remote Asset API

The Bazel Remote Asset API provides a mechanism for managing external dependencies in a centralized way.

More precisely, it maps external resource identifiers (such as URLs or Git repositories) to content stored in a content-addressable storage (CAS).

In practice, this allows a server to:

Fetch external resources (e.g. tarballs, Git repos)
Store them in CAS
Serve them to clients by digest

When used via Bazel’s remote downloader, this effectively acts as a download proxy/cache: instead of every developer machine and CI runner downloading dependencies independently, requests go through a central service that can fetch and cache them once.

How to Use

Getting started is straightforward: pass --experimental_remote_downloader=SERVER_ADDRESS either on the command line or in your .bazelrc.

This configures Bazel to route external downloads through a Remote Asset API–compatible service.

Before using it, ensure your remote cache/server supports the API. Many commercial solutions do, and the popular open-source bazel-remote supports (a subset of) it as well—though support is still marked experimental.

A Note on the Experimental Flag

Although the flag is prefixed with experimental, the feature has been available for some time and is widely used in practice. There is some good info on the Bazel Slack about it.

Conclusion

Combined with Bazel’s repository cache, the Remote Asset API provides a nice way to improve reliability when fetching external repos. It reduces reliance on third-party availability while avoiding the operational overhead of fully vendoring or mirroring all dependencies.

A Better Way to Ignore Files in Bazel with repo.bazel

Sun, 19 Apr 2026 22:22:10 +0200

In the Bazel world, we don’t always want it to track all the files in our repository. A typical example is ignoring the .git directory, as it can grow quite large over time. Additionally, some IDE integrations like rules_xcodeproj don’t work particularly well when it is present.

Traditionally, to instruct Bazel to ignore directories and files, we used the .bazelignore file, which requires explicitly listing paths to ignore. This works, but it has an important limitation: .bazelignore does not support glob patterns. As a result, we often need to update the file whenever new directories should be ignored—and it’s easy to forget to do so.

Introducing `repo.bazel`

repo.bazel is a simple configuration file that allows us to achieve similar behavior, but with support for glob patterns. It is a relatively recent addition to Bazel, introduced around the same time as bzlmod.

An example repo.bazel file looks like this:

ignore_directories([
    # Ignore all .build directories produced by Swift Package Manager
    "**/.build",
    # Ignore Node modules directories
    "**/node_modules",
])

And that’s it.

Conclusion

This approach builds on the same idea as .bazelignore, but adds a few quality-of-life improvements—most notably, support for glob patterns.

For more information, see the official Bazel documentation.

Reconfiguring bazel downloader

Sun, 12 Apr 2026 16:00:36 +0200

There are many security as well as practical reasons why one might need to reconfigure Bazel’s downloading behavior. One concrete case that I ran into fairly recently was Google rate-limiting our CI for an unknown reason. To work around that, I needed to redirect the downloader to a mirror. There are many ways to achieve that, like patching individual rules (tedious), using an internal registry (doesn’t solve everything), etc.

Bazel downloader config

Bazel offers a way to configure its downloader in a very simple manner. Unfortunately, it is not very well documented, but there are various resources online as well as the actual Bazel source, which explains it quite nicely. To enable it, we simply pass --downloader_config=<path_to_file> either on the command line or in .bazelrc.

File structure and syntax

The structure is easy to understand because it allows only a small set of directives:

allow host.name to allow a specific domain
block host.name to block a certain domain (also supports block * to block everything except what is explicitly allowed)
rewrite pattern replacement to rewrite URLs using regex
all_blocked_message message — a message shown if all candidate URLs end up blocked

Rewrite directive

Because all other directives are fairly self-explanatory, I will focus only on rewrite.

As an example, if we want to ensure that all GitHub downloads are redirected to an internal Artifactory, we could write a file like this:

rewrite github.com/(.*) internal.artifactory.example.com/$1

Of course, it is possible to define more sophisticated rewrite patterns, e.g.:

rewrite android.googlesource.com/platform/dalvik/\+archive/([0-9a-f]+)\.tar\.gz mirror.bazel.build/android.googlesource.com/platform/dalvik/+archive/$1.tar.gz
rewrite android.googlesource.com/platform/dalvik/\+archive/([0-9a-f]+)\.tar\.gz android.googlesource.com/platform/dalvik/+archive/$1.tar.gz

This rewrites requests for android.googlesource.com to mirror.bazel.build for this specific dalvik archive. The second rewrite directive ensures that Bazel falls back to the original URL if the mirror is unavailable.

Evaluation order

Bazel applies the directives in the following order, regardless of their position in the file:

rewrite
allow
block

Comments

It is possible to add comments using # at the beginning of a line. Keep in mind that inline comments are not supported.

Conclusion

Typically, this is not needed very often, but it is good to keep the option in the back of your mind so you can reach for it when needed.

Bazel Output Groups: Producing Outputs on Demand

Sun, 05 Apr 2026 20:39:47 +0200

Typically, when writing a Bazel rule, we produce outputs using the DefaultInfo provider. However, there are cases where we want to produce additional outputs only on demand.

Enter output groups

Simply put, output groups are a way to tell Bazel to produce different sets of outputs instead of—or in addition to—the default outputs. For example, we might want to generate debug symbols, but we don’t need them unless explicitly requested.

Smallest possible example

Here is a minimal rule that demonstrates the use of output groups:

def _impl(ctx):
    out1 = ctx.actions.declare_file("main.txt")
    out2 = ctx.actions.declare_file("debug.txt")

    ctx.actions.write(out1, "main output")
    ctx.actions.write(out2, "debug output")

    return [
        DefaultInfo(files = depset([out1])),
        OutputGroupInfo(
            debug = depset([out2]),
        ),
    ]

my_rule = rule(
    implementation = _impl,
)

Notice how easy it is to use output groups. OutputGroupInfo is just another provider—a key-value mapping where, in this case, debug is the key (the output group name), and out2 is the value wrapped in a depset.

Requesting the debug output

If we instantiate this rule in a BUILD file:

my_rule(
    name = "groups",
)

We can build it:

bazel build :groups

This produces:

INFO: Analyzed target //:groups (5 packages loaded, 7 targets configured).
INFO: Found 1 target...
Target //:groups up-to-date:
  bazel-bin/main.txt
INFO: Elapsed time: 0.119s, Critical Path: 0.00s
INFO: 2 processes: 2 internal.
INFO: Build completed successfully, 2 total actions

The important part here is bazel-bin/main.txt. This happens because we did not tell Bazel to include outputs from the debug output group.

To do that, we use the --output_groups flag and specify the group name (in this case, debug):

bazel build :groups --output_groups=debug

Output:

INFO: Analyzed target //:groups (0 packages loaded, 0 targets configured).
INFO: Found 1 target...
Target //:groups up-to-date:
  bazel-bin/debug.txt
INFO: Elapsed time: 0.065s, Critical Path: 0.00s
INFO: 2 processes: 2 internal.
INFO: Build completed successfully, 2 total actions

Now the debug file is produced.

An important detail: debug.txt is produced instead of main.txt, not in addition to it. To request both the default outputs and an output group at the same time, use the + prefix:

bazel build :groups --output_groups=+debug

This produces both files:

INFO: Analyzed target //:groups (5 packages loaded, 7 targets configured).
INFO: Found 1 target...
Target //:groups up-to-date:
  bazel-bin/debug.txt
  bazel-bin/main.txt
INFO: Elapsed time: 0.108s, Critical Path: 0.00s
INFO: 3 processes: 3 internal.
INFO: Build completed successfully, 3 total actions

Conclusion

Output groups are simple to use, both when defining rules and when consuming them. They’re a small feature, but an extremely useful one.

What Bazel Really Runs (and How to See It)

Sun, 29 Mar 2026 18:16:03 +0200

There comes a time when working with Bazel when we want to understand the command-line flags used to build our code. For example, you might want to see what flags are being passed to swiftc. Up until Bazel 9, we would typically rely on --subcommands, but it could get quite verbose.

Action graph query

In addition to the standard bazel query command, there are also bazel cquery (configurable query) and bazel aquery (action graph query). Each of these helps us explore different parts of the build graph. Since we’re interested in inspecting command-line flags, aquery is the right tool—it exposes all declared actions, including the exact commands being executed.

For a project like this iOS template, we can explore how Swift code is compiled by running:

bazel aquery //app:app.library --output=commands

Which produces output like:

bazel-out/darwin_arm64-opt-exec/bin/external/rules_swift+/tools/worker/worker swiftc -target arm64-apple-macos12.6 -sdk __BAZEL_XCODE_SDKROOT__ -file-prefix-map '__BAZEL_XCODE_DEVELOPER_DIR__=/PLACEHOLDER_DEVELOPER_DIR' '-Xwrapped-swift=-bazel-target-label=@@//app:app.library' -emit-object -output-file-map bazel-out/darwin_arm64-fastbuild/bin/app/app.library.output_file_map.json -Xfrontend -no-clang-module-breadcrumbs -emit-module-path bazel-out/darwin_arm64-fastbuild/bin/app/app.swiftmodule '-enforce-exclusivity=checked' -emit-const-values-path bazel-out/darwin_arm64-fastbuild/bin/app/app.library_objs/source/ContentView.swift.swiftconstvalues -Xfrontend -const-gather-protocols-file -Xfrontend external/rules_swift+/swift/toolchains/config/const_protocols_to_gather.json -DDEBUG -Onone -Xfrontend -internalize-at-link -Xfrontend -no-serialize-debugging-options -enable-testing -disable-sandbox -gline-tables-only '-Xwrapped-swift=-file-prefix-pwd-is-dot' -file-prefix-map '__BAZEL_XCODE_DEVELOPER_DIR__=/PLACEHOLDER_DEVELOPER_DIR' -file-compilation-dir . -module-cache-path bazel-out/darwin_arm64-fastbuild/bin/_swift_module_cache -Ibazel-out/darwin_arm64-fastbuild/bin/modules/Models -Ibazel-out/darwin_arm64-fastbuild/bin/modules/API '-Xwrapped-swift=-macro-expansion-dir=bazel-out/darwin_arm64-fastbuild/bin/app/app.library.macro-expansions' -Xcc -iquote. -Xcc -iquotebazel-out/darwin_arm64-fastbuild/bin -Xfrontend -color-diagnostics -enable-batch-mode -module-name app -index-store-path bazel-out/darwin_arm64-fastbuild/bin/app/app.library.indexstore -index-ignore-system-modules '-Xwrapped-swift=-global-index-store-import-path=bazel-out/_global_index_store' -enable-bare-slash-regex -Xfrontend -disable-clang-spi -enable-experimental-feature AccessLevelOnImport -parse-as-library -static -Xcc -O0 -Xcc '-DDEBUG=1' -Xfrontend '-checked-async-objc-bridging=on' app/source/ContentView.swift app/source/MainApp.swift
...

At first glance, this output looks overwhelming. But if you break it down, it’s simply Bazel invoking tools with the appropriate flags.

Doing something useful

While this output can help us understand what is being executed and how, it becomes much more powerful when used comparatively.

One practical approach is to diff this output across ruleset versions or Bazel releases. For example:

bazel aquery //app:app.library --output=commands > commands.txt

You can generate one file per version and use standard diffing tools to spot regressions or better understand what changed between versions.

Making it executable

In a Bazel 9 video by aspect.build, Alex Eagle shared an interesting idea: turning aquery output into an executable shell script.

That idea is what got me intrigued. While the output isn’t directly executable, it seems feasible to get there by replacing placeholder variables, adjusting formatting, and fiddling with cwd. With a bit of effort, this could become a powerful debugging tool.

Conclusion

This is a small quality-of-life improvement in Bazel 9, but it unlocks a very practical debugging technique.

Adin Ćebić

Exploring map_directory in Bazel 9

Registering actions dynamically

map_directory in action

Conclusion

Bazel, APFS Clones, and Disk Space

Using APFS clones from Swift

Conclusion

How to Reduce Bazel Disk Space Usage Across Git Worktrees

Enter bb-clientd

Conclusion

Preventing Transitive Swift Imports with Bazel

Layering check via rules_swift

Conclusion

Profiling Starlark Memory Usage in Bazel

Setting up

Dealing with gathered data

Conclusion

Testing Bazel Remote Build Execution Locally with actiond

actiond from hermeticbuild

Pointing Bazel at it

Conclusion

Less Boilerplate for Bazel Transitions

Enter with_cfg.bzl

Applying a transition to a plain swift_library

Prior art

Conclusion

Pruning Unused Action Inputs in Bazel

A simple example

The select_one rule

The tool itself

Putting it all together

Conclusion

A Note on Bazel’s config.exec()

Why?

Conclusion

Making Bazel Module Extensions Work Together with override_repo

Overriding a repository

Conclusion

Stamping iOS Builds with Bazel

Workspace status script

Reading the value at build time

A word on the stamp attribute

Reading the value at runtime

Conclusion

Making Developer Tools Available Through Bazel

Problems with Homebrew for developer tools

brew install …

Distributing tools

Using Bazel and rules_multitool

How it works

Setting it up

Making it more convenient

Conclusion

Avoiding .DS_Store Cache Misses in Bazel

The problem

The solution

Conclusion

External Repo File Checks In Bazel 9

Prior Art

Conclusion

Cleaning up old Bazel patterns

Sets

Remove function_transition_allowlist when creating transitions

repo_name is usually no longer worth keeping

Start using REPO.bazel

compatibility_level is a no-op

A word about flags

Conclusion

Running Multiple Bazel Targets in a Single Invocation

Enter rules_multirun

Running multiple targets

Execution modes

Why testonly

Other rules from rules_multirun

Conclusion

Suppressing Warnings in External Swift Dependencies with Bazel

REPO.bazel to the rescue

Suppressing warnings in external Swift libraries

Conclusion

A word on the `stamp` attribute

Start using `REPO.bazel`

`compatibility_level` is a no-op

Introducing `repo.bazel`