Adin Ćebić

A Practical Introduction to Bazel Persistent Workers

Sun, 10 May 2026 17:45:12 +0100

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 20:41:59 +0100

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 16:40:57 +0100

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 21:22:10 +0100

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 15:00:36 +0100

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 19:39:47 +0100

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 17:16:03 +0100

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.

Bazel split transitions

Sun, 22 Mar 2026 10:48:39 +0100

A couple of articles ago, I touched on Bazel transitions. In that context, I was referring to 1:1 transitions—transitions that change the single configuration of a target. Split transitions, on the other hand, are 1:N, meaning they build the same target in multiple configurations.

Multi-arch build

An obvious example where split transitions are useful is multi-platform (or multi-architecture) builds. Because my background is in Swift and Apple platforms, I immediately think of device and simulator builds.

You can think of a split transition as turning a single dependency edge:

A → B

into multiple ones:

A → B (device)
  → B (simulator)

In other words, a single dependency is “split” into multiple configurations.

Multi-platform Swift library

Let’s imagine we want to build a swift_library for both iOS device and simulator—for example, to validate both environments in CI or to produce multi-platform artifacts.

Note: In real-world Apple builds, you would typically rely on existing transition support provided by rules_apple rather than defining your own. This example is intentionally simplified to illustrate how split transitions work under the hood.

To achieve this, we need to define a transition and a wrapper rule.

def _split_transition_impl(_settings, _attr):
    return {
        "device": {"//command_line_option:platforms": "@apple_support//platforms:ios_arm64"},
        "sim": {"//command_line_option:platforms": "@apple_support//platforms:ios_sim_arm64"},
    }

split_transition = transition(
    implementation = _split_transition_impl,
    inputs = [],
    outputs = ["//command_line_option:platforms"],
)

This illustrates why they’re called split transitions: a single dependency edge is expanded into multiple configurations, each identified by a key (device, sim).

Next, we define a rule that applies the transition:

def _multi_platform_swift_library(ctx):
    propagated_files = []

    for split_deps in ctx.split_attr.deps.values():
        for dep in split_deps:
            propagated_files.append(dep[DefaultInfo].files)

    return [
        DefaultInfo(
            files = depset(transitive = propagated_files),
        ),
    ]

multi_platform_swift_library = rule(
    implementation = _multi_platform_swift_library,
    attrs = {
        "deps": attr.label_list(cfg = split_transition),
    },
)

Here, ctx.split_attr.deps is a dictionary where each key (device, sim) maps to the list of dependencies built in that configuration.

We simply propagate the files from the dependencies so that they are built—this keeps the example minimal while still demonstrating the transition.

Finally, in BUILD.bazel, we define targets using these rules:

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

swift_library(
    name = "lib",
    module_name = "Library",
    srcs = ["main.swift"],
)

multi_platform_swift_library(
    name = "mp",
    deps = [":lib"],
)

To verify that the transition has been applied, we can use Bazel’s configuration query:

bazel cquery //:mp --transitions=full

This will produce output similar to:

INFO: Analyzed target //:mp (0 packages loaded, 0 targets configured).
INFO: Found 1 target...
NoTransition -> //:mp (680dcaf)
  deps#//:lib#(Starlark transition:/Users/adincebic/developer.noindex/split/rules.bzl:8:30 + (TestTrimmingTransition + ConfigFeatureFlagTaggedTrimmingTransition)) -> 58f99a6, c9f1a2b
    platforms:[@@bazel_tools//tools:host_platform] -> [[@@apple_support+//platforms:ios_arm64], [@@apple_support+//platforms:ios_sim_arm64]]
  $allowlist_function_transition#@bazel_tools//tools/allowlists/function_transition_allowlist:function_transition_allowlist#(null transition) -> 
INFO: Elapsed time: 0.067s, Critical Path: 0.00s
INFO: 0 processes.
INFO: Build completed successfully, 0 total actions

Notice how //:lib is configured twice—once for each platform (ios_arm64 and ios_sim_arm64). This confirms that the split transition produced multiple configurations.

Conclusion

Bazel transitions are a powerful tool, but they should be used sparingly. They fundamentally alter the build graph, and split transitions in particular can significantly increase its size since dependencies may be built multiple times.

Conceptually, however, split transitions are no more complex than standard 1:1 transitions—they simply require using split_attr instead of attr, and thinking in terms of one dependency becoming many.

How to Fix Xcode Source Editor Extensions That Don’t Appear in the Editor Menu

Sun, 15 Mar 2026 19:35:16 +0100

Recently I needed to develop my own Xcode source editor extension. The reasons for doing so aren’t relevant here, but the process quickly led me into an unexpected roadblock.

TL;DR: In your extension target settings, set XcodeKit.framework → “Embed without signing” under the General tab.

Extension not showing up in Xcode

After following Apple’s official guide for creating a source editor extension (a macOS app with an extension target), I ran the extension scheme to test it. However, the extension neither appeared in Xcode nor executed any code.

Normally, a source editor extension should appear in two places:

macOS System Settings (Extensions → Xcode Source Editor)
Xcode’s Editor menu

In my case, the extension showed up in System Settings but did not appear in Xcode.

Asking around

Like most developers, I immediately turned to Google and AI tools. It quickly became clear that this issue is not uncommon. Unfortunately, none of the suggested workarounds solved my problem.

Sifting through Xcode logs

After exhausting the usual fixes, I wondered whether Xcode might be logging something useful while attempting to load extensions.

Using the unified logging system, I started streaming Xcode logs with a predicate to filter relevant messages:

log stream --style compact --predicate 'process == "Xcode" && (eventMessage CONTAINS[c] "EditorExtension" || eventMessage CONTAINS[c] "XcodeKit")'

After running the extension again, I noticed the following message:

Xcode Extension does not incorporate XcodeKit

This was finally a clue.

Looking at existing extensions

My next step was to inspect existing open-source extensions. I looked at projects like SwiftFormat and compared their release artifacts with the one produced by my own extension.

Missing `XcodeKit.framework`

While inspecting the extension bundle, one difference stood out immediately: my extension was not bundling XcodeKit.framework, while SwiftFormat’s extension was.

I also noticed that SwiftFormat’s release workflow explicitly ensures that XcodeKit.framework is bundled into the extension archive.

The fix: Embed without signing

It turns out the default Xcode template for source editor extensions is misconfigured.

By default, XcodeKit.framework is set to “Do Not Embed” in the extension target settings. Because of this, the framework never gets bundled with the extension.

Changing the setting to:

General → Frameworks, and Libraries → XcodeKit.framework → “Embed without signing”

fixes the issue and allows Xcode to load the extension correctly.

Closing thoughts

Problems like this are especially frustrating when there’s little to no documentation online and even AI tools can’t identify the cause.

One useful takeaway is that Apple heavily relies on the Unified Logging System across their apps, tools and macOS in general. When something misbehaves, inspecting logs can provide a path forward.

Managing Bazel Flags in Monorepos with Flagsets (PROJECT.scl)

Sun, 08 Mar 2026 14:10:15 +0100

Bazel’s flagsets, or PROJECT.scl, are an approach aimed at solving project-specific flags in a monorepo. It leverages Starlark as its language, or more precisely, a subset of Starlark. This is in contrast to the traditional .bazelrc, which uses its own line-based language and has no formal specification.

Current state of the art

At the time of writing this, we are almost certainly all using .bazelrc files to hide away command line flags as well as to define configs (de facto sets of flags). My take is that .bazelrc is fine and will continue to work well for many people in a multi-repo setup. However, .bazelrc not only does not scale well in monorepos (yes, it is possible to compose them via import) but it can also lead to incorrect builds during day-to-day development.

Say we are working in a monorepo with both iOS and Android apps and we want to build iOS by executing:

bazel build //ios:app

At first glance, nothing seems wrong. However, all the flags that we use for Android are also applied when building iOS, and vice versa. Granted, this can be fine, but there might be a feature flag for C++ that both platforms use in different ways. In that scenario we always need to make sure that we explicitly apply the given flag differently for each platform or find some other way.

I’m sure there are many more examples one could come up with.

The solution

Project-specific PROJECT.scl files, aka flagsets. They were introduced at BazelCon 2025 in Bazel 9 as an experimental feature. However, they are currently not behind a feature flag, so if you are on Bazel 9 you can start using them today and help discover interesting corner cases.

Example iOS app

Imagine we are in a monorepo where each app is its own project (separate directory) like iOS/, Android/, and so on. So for the iOS app we would want to define dev and store configurations which obviously build the app in different ways. We would create a PROJECT.scl in the iOS subdirectory and give it the following contents:

load("//:project_proto.scl", "buildable_unit_pb2", "project_pb2")

project = project_pb2.Project.create(
    buildable_units = [
        # Since this buildable unit sets "is_default = True", these flags apply
        # to any target in this package or its subpackages by default. You can
        # also request these flags explicitly with "--scl_config=dev_config" or "--scl_config=store_config".
        buildable_unit_pb2.BuildableUnit.create(
            name = "dev_config",
            flags = [
                "--compilation_mode=dbg",
            ],
            is_default = True,
            description = "Default debug configuration used for development.",
        ),

        buildable_unit_pb2.BuildableUnit.create(
            name = "store_config",
            flags = [
                "--compilation_mode=opt",
                '--ios_multi_cpus=arm64',
            ],
            description = "Store configuration.",
        ),
    ],
)

I feel like this is pretty self-explanatory and demonstrates the basic idea. When building the app, Bazel 9 will take the PROJECT.scl closest to the target on the filesystem into account when applying flags. If we want to build for the store, the only thing required is to set --scl_config=store_config, much like --config in .bazelrc.

Enforcement policies

One of the more interesting features of flagsets is that we can define enforcement policies which basically can either:

WARN: warns you if you add additional flags via the command line or .bazelrc. This is the default, so it doesn’t have to be explicitly specified.
COMPATIBLE: disallows setting conflicting flags via the command line or .bazelrc, but allows flags that do not interfere with those specified in PROJECT.scl.
STRICT: disallows setting any flags via the command line or .bazelrc, so everything must be defined in the relevant PROJECT.scl.

To set one of the policies above, we use the enforcement_policy attribute on project_pb2.Project.create:

load("//:project_proto.scl", "buildable_unit_pb2", "project_pb2")

project = project_pb2.Project.create(
    enforcement_policy = "STRICT",
    buildable_units = [
        buildable_unit_pb2.BuildableUnit.create(
            name = "dev_config",
            flags = [
                "--compilation_mode=dbg",
            ],
            is_default = True,
            description = "Default debug configuration used for development.",
        ),

        buildable_unit_pb2.BuildableUnit.create(
            name = "store_config",
            flags = [
                "--compilation_mode=opt",
                '--ios_multi_cpus=arm64',
            ],
            description = "Store configuration.",
        ),
    ],
)

After building the target we would get the following output if additional flags are applied other than those in PROJECT.scl:

INFO: Reading project settings from //ios:PROJECT.scl.
ERROR: Cannot parse options: This build uses a project file (//:PROJECT.scl) that does not allow output-affecting flags in the command line or user bazelrc. Found ['--macos_minimum_os=12.6', '--flag_alias=build_python_zip=@@rules_python+//python/config_settings:build_python_zip', '--ios_simulator_version=18.5', '--flag_alias=incompatible_default_to_explicit_init_py=@@rules_python+//python/config_settings:incompatible_default_to_explicit_init_py', '--modify_execution_info=^(BitcodeSymbolsCopy|BundleApp|BundleTreeApp|DsymDwarf|DsymLipo|GenerateAppleSymbolsFile|ObjcBinarySymbolStrip|CppLink|ObjcLink|ProcessAndSign|SignBinary|SwiftArchive|SwiftStdlibCopy)$=+no-remote,^(BundleResources|ImportedDynamicFrameworkProcessor)$=+no-remote-exec', '--flag_alias=python_path=@@rules_python+//python/config_settings:python_path', '--features=swift.index_while_building', '--macos_minimum_os=13', '--incompatible_strict_action_env', '--features=swift.use_global_index_store', '--flag_alias=experimental_python_import_all_repositories=@@rules_python+//python/config_settings:experimental_python_import_all_repositories', '--host_macos_minimum_os=13', '--features=swift.use_global_module_cache']. Please remove these flags or disable project file resolution via --noenforce_project_configs.

Target-specific flags

Another interesting aspect of flagsets is the ability to set flags on a per-target basis. There is an attribute called target_patterns on buildable_unit_pb2.BuildableUnit.create:

            target_patterns = [
                "//target_specific:one",
            ],

The following patterns are supported (taken from Bazel documentation and examples):

//some:target (specific target)
-//some:target (exclude //some:target from this filter)
//some/path/... (all targets below a path)
-//some/path/... (exclude all targets below a path)

In conclusion

I believe this is a great step forward for improving how Bazel flags are managed. It is still very early days and there are many unanswered questions, such as what happens if a project depends on another project, and many others I probably haven’t even thought of yet. As time goes on, we will discover best practices and flagsets as a feature of Bazel will evolve to support more scenarios.

To learn more about the decisions that went into the design of flagsets, please see this talk on Youtube by the Bazel team.

Composing Bazel rules with subrules

Sun, 01 Mar 2026 12:59:58 +0100

Bazel subrules are a lesser-known mechanism for splitting rule functionality into smaller, reusable building blocks. They are designed to improve rule architecture by encapsulating implicit dependencies, toolchains, and action logic — without passing the entire ctx (“god object”) around.

In the past, we achieved similar reuse through plain Starlark helper functions. While that works, it often requires threading ctx through multiple layers, which reduces encapsulation and makes refactoring harder.

Subrules

A subrule is similar to a rule in that it can create actions during analysis. However, it operates under strict encapsulation constraints and exposes only a reduced context API.

Let’s start with a simple example.

def _hello_subrule_impl(ctx, name):
    hello_file = ctx.actions.declare_file(ctx.label.name + name + ".txt")
    return hello_file

hello_subrule = subrule(
    implementation = _hello_subrule_impl,
)

def _hello_impl(ctx):
    hello_file = hello_subrule(name = "Example")

    ctx.actions.write(
        output = hello_file,
        content = "Hello, world!",
    )

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

hello = rule(
    implementation = _hello_impl,
    subrules = [hello_subrule],
)

We define hello_subrule using subrule() and provide its implementation.
The implementation function receives a restricted ctx (a SubruleContext) and any additional parameters.
When defining the hello rule, we must declare subrules = [hello_subrule].
Inside the rule implementation, we call the subrule like a normal function:

   hello_file = hello_subrule(name = "Example")

We do not call it via ctx. The ctx argument is automatically injected.

Subrules may return arbitrary values — not just providers.

Important: Subrules Must Be Declared

If you call a subrule but forget to list it in the subrules = [...] parameter of the rule (or another subrule), Bazel raises a runtime error during analysis.

What You Can and Cannot Do

Subrules can create actions just like rules, but they are intentionally constrained for better encapsulation.

All Attributes Must Be Private

Subrules can declare only implicit dependencies, and their attribute names must begin with an underscore.

This results in an error:

hello_subrule = subrule(
    implementation = _hello_subrule_impl,
    attrs = {
        "compiler": attr.label(),
    },
)

Error in subrule: illegal attribute name 'compiler': subrules may only define private attributes (whose names begin with '_').

Attributes Must Be label or label_list

Subrule attributes may only be attr.label() or attr.label_list().

Other attribute types (e.g., attr.string(), attr.bool()) are not allowed:

attrs = {
    "_compiler": attr.string(),
}

Produces:

Error in subrule: bad type for attribute '_compiler': subrule attributes may only be label or lists of labels.

Private attributes Require Defaults

Because subrule attributes are private implicit dependencies and cannot be set by users of the rule, they must define a default value (or a late-bound default label).

They must be spelled out as implementation function arguments.

The Context Is Restricted

Subrules receive a SubruleContext, not a full RuleContext.

Attempting to access ctx.attr will fail:

def _hello_subrule_impl(ctx, name):
    print(ctx.attr.surname)
    return None

Error: 'subrule_ctx' value has no field or method 'attr'

Available Fields on subrule context:

In the current API, the available members are:

actions
fragments
label
toolchains

Toolchains and Execution Groups

Subrules can declare:

subrule(
    implementation = _implementation,
    toolchains = [...],
    exec_group = ...,
    subrules = [...],
)

This allows:

Toolchain requirements per subrule
Encapsulation of execution groups

Only one exec group per subrule is supported.

Nested Subrules

A subrule may declare and call other subrules by using the subrules = [...] parameter.

Why Subrules Matter

Subrules address several long-standing architectural issues in Starlark rule design:

Avoid passing ctx everywhere
Encapsulate implicit dependencies
Encapsulate toolchain resolution
Improve composability
Make helper-function patterns more structured

Takeaways

Subrules are a powerful architectural improvement for composing complex Bazel rules, just remember:

You must declare subrules using subrules = [...].
You call a subrule like a function — not through ctx.
ctx is automatically injected.
Attributes must be private and label-based.
The context is intentionally restricted.
Subrules operate only at analysis time.

They are not replacements for existing mechanisms, but they are a much cleaner way to encapsulate reusable rule logic compared to traditional helper functions.

As adoption increases, they will likely become a default way of composing complex rules.

Applying Bazel Transitions to Third-Party Rules the Right Way

Sun, 22 Feb 2026 14:37:56 +0100

Historically, it has been tedious to apply transitions to rules we don’t control. You either had to maintain a fork, apply a patch, or wrap the rule — which is particularly annoying because you then have to manually forward the providers of the underlying rule.

Enter Rule Extensions

Bazel 8 introduced rule extensions, which allow you to augment an existing rule — somewhat similar to subclassing in object-oriented languages. Instead of copying or wrapping a rule manually, you can define a new rule that delegates to a parent rule while modifying selected behavior.

A Simple Transition

Let’s first create a transition that forces opt as the compilation mode:

def _opt_transition_impl(_settings, _attr):
    return {"//command_line_option:compilation_mode": "opt"}

opt_transition = transition(
    implementation = _opt_transition_impl,
    inputs = [],
    outputs = ["//command_line_option:compilation_mode"],
)

Nothing fancy — this transition forces the rule it’s applied to to always build in opt, regardless of the --compilation_mode specified on the command line.

Applying the Transition

Here I’m demonstrating this with swift_library, but the concept is the same regardless of the rule:

opt_swift_library = rule(
    implementation = lambda ctx: ctx.super(),
    parent = swift_library,
    cfg = opt_transition,
)

That’s it. The new opt_swift_library behaves exactly like swift_library, except it always builds in opt mode.

For the sake of completeness, here is the entire .bzl file:

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

def _opt_transition_impl(_settings, _attr):
    return {"//command_line_option:compilation_mode": "opt"}

opt_transition = transition(
    implementation = _opt_transition_impl,
    inputs = [],
    outputs = ["//command_line_option:compilation_mode"],
)

opt_swift_library = rule(
    implementation = lambda ctx: ctx.super(),
    parent = swift_library,
    cfg = opt_transition,
)

Wrapping Up

There’s much more you can do with rule extensions, but being able to easily apply transitions to third-party rules is already a huge win.

To learn more about what’s possible, check out Keith’s excellent article on this topic.

Creating Custom Command-Line Flags in Bazel

Sat, 21 Feb 2026 12:40:54 +0100

It’s fairly common to need to alter your builds based on a command-line flag. Maybe you want to change the distribution target for a mobile app or enable additional debug functionality. An easy way to do that is via a custom command-line flag.

This is a topic where Bazel newcomers often struggle, so let’s explore how to create custom flags in Bazel.

Build Settings

A build setting is a rule—just like any other rule—but with additional capabilities. Specifically, build settings allow us to define custom command-line flags that influence the build configuration.

Pre-defined Settings

Because build settings are rules, we can write our own. However, bazel-skylib provides several commonly used build settings out of the box.

You can see the full list in the skylib repository.

For simplicity, we’ll use a pre-defined setting in this article. Keep in mind, though, that you’re not limited to what skylib offers—you can implement your own build setting if needed.

Creating a Flag

Suppose we want to build differently for our local development environment versus what we release to the App Store. We’ll call this a flavor, with two variants:

dev
store

To create a flag, we need to instantiate a build setting in BUILD.bazel:

load("@bazel_skylib//rules:common_settings.bzl", "string_flag")

string_flag(
    name = "flavor",
    values = ["dev", "store"],
    build_setting_default = "dev",
)

Because this is a target, it has a label. That’s why we pass it on the command line using label syntax:

bazel build //:my_target --//:flavor=store

However, defining the flag alone is not enough.

Reacting to Build Settings

Bazel does not branch directly on build settings. Instead, it evaluates configuration conditions, represented by config_setting targets.

So we need to associate our flag with configuration conditions:

config_setting(
    name = "dev",
    flag_values = {":flavor": "dev"},
    visibility = ["//visibility:public"],
)

config_setting(
    name = "store",
    flag_values = {":flavor": "store"},
    visibility = ["//visibility:public"],
)

Here’s the mental model:

string_flag defines a configurable value.
config_setting defines a configuration condition.
select() switches on config_setting.

This separation is important: select() operates on config_setting targets, not directly on flags.

Using `select()`

Now that we have configuration conditions, we can branch using select().

To demonstrate that our flag works, we’ll create a simple genrule that writes which flavor was selected:

genrule(
    name = "which_flavor",
    outs = ["output.txt"],
    cmd = select({
        ":dev": "echo dev > $@",
        ":store": "echo store > $@",
    }),
)

Now build the target:

bazel build :which_flavor --//:flavor=store

You should see something like this:

INFO: Analyzed target //:which_flavor (6 packages loaded, 10 targets configured).
INFO: Found 1 target...
Target //:which_flavor up-to-date:
  bazel-bin/output.txt
INFO: Elapsed time: 0.297s, Critical Path: 0.02s
INFO: 2 processes: 1 internal, 1 darwin-sandbox.
INFO: Build completed successfully, 2 total actions

Opening bazel-bin/output.txt will reveal:

store

Closing Thoughts

To create a custom command-line flag in Bazel, remember:

You need a build setting (string_flag, bool_flag, etc.).
You need one or more config_setting targets that describe configuration conditions.
You use select() to branch on those configuration conditions.

If you’re not writing custom rules, using pre-defined settings from skylib is probably the right approach in most cases. If you need more flexibility, you can write your own build setting rule—but that’s a topic for another day.

Using features in bazel rules

Sun, 08 Feb 2026 11:02:02 +0100

Often we want to allow users of our Bazel rules to enable or disable functionality on an as-needed basis. While Bazel offers several mechanisms for this, features are the simplest—and probably the right—approach for the majority of cases.

Using features

Features can be enabled in two ways:

On the command line: --features=my_feature
As a rule attribute: features = ["my_feature"]

NOTE: The command-line approach is cumulative, meaning multiple features can be enabled by repeating the --features flag with different values.

Reading features from rules

Say we have the following rule that writes a name to a file:

def _hello_impl(ctx):
    content = ctx.attr.first_name
    out = ctx.actions.declare_file(ctx.label.name + ".txt")
    ctx.actions.write(
        output = out,
        content = content,
    )
    return DefaultInfo(files = depset([out]))

hello = rule(
    implementation = _hello_impl,
    attrs = {
        "first_name": attr.string(),
    },
)

Now imagine we want to ensure there is a trailing newline at the end of the file, but we want this behavior to be opt-in. The simplest way to achieve that is:

Check whether ctx.features contains hello.trailing_newline
If yes, append \n
Otherwise, keep the content as is

if "hello.trailing_newline" in ctx.features:
    content = ctx.attr.first_name + "\n"

To apply the feature from the command line:

bazel build :hello --features=hello.trailing_newline

Or directly on the target:

hello(
    name = "hello",
    first_name = "Adin",
    features = ["hello.trailing_newline"],
)

Disabling features

One neat trick about Bazel features is that they can be explicitly disabled, both on the command line and via the features attribute, by prefixing the feature name with -.

For example, to disable the hello.trailing_newline feature:

bazel build :hello --features=-hello.trailing_newline

Inside the rule implementation, Bazel exposes a conveniently named ctx.disabled_features list, which contains all features explicitly disabled for that target.

A few things to know

Features are global, not scoped to a specific rule. This is why prefixing feature names (for example, hello.trailing_newline) is strongly recommended. rules_swift follows the same convention.
Changing --features invalidates the analysis cache.
Bazel also provides a --host_features flag, which applies to the execution (host) configuration.

Wrapping up

This is one of those simple mechanisms that turns out to be extremely useful. So next time you think about adding an extra attribute to a rule, think twice—features are likely the better choice.

Executing actions from Bazel aspects

Sun, 01 Feb 2026 09:56:10 +0100

So far I went through writing the aspect, but I haven’t shown how to run actions from it to do something useful. Remember: we can do very little during Starlark evaluation (Bazel’s analysis phase). If we want to read files, inspect sources, or produce results, the work has to happen in the execution phase by running actions.

NOTE: Before continuing, it helps to read my earlier articles on Bazel aspects, since I’m going to assume that background.

ctx.actions

Every aspect and rule gets a ctx object, which gives us access to ctx.actions — including run(). Sticking with the “unused Swift deps” example, here’s what invoking a tool looks like:

ctx.actions.run(
    inputs = [input] + source_files,
    outputs = [out],
    executable = ctx.executable._tool,
    arguments = [arguments],
)

This snippet captures the essentials of a Bazel action:

Inputs: all files the tool may read
Outputs: files the tool is expected to generate
Executable: the tool binary itself
Arguments: the tool’s command-line arguments

Bazel uses these declarations to compute action keys, decide when work must be re-executed, and make remote/local caching correct.

Inputs

Here, inputs are:

a JSON file that describes what we want to be analyzed
the Swift source files to scan

First, we build the JSON payload:

payload = {
    "targetLabel": str(target.label),
    "sources": [f.path for f in source_files],
    "deps": deps_to_analyze,
}

encoded_json = json.encode(payload)
input = ctx.actions.declare_file(ctx.label.name + "_input.json")

Like I described in my first article, declaring the file is not enough — we also need an action to write it:

ctx.actions.write(
    output = input,
    content = encoded_json,
)

Outputs, arguments and tool

In this case the tool produces a single JSON output that contains the unused dependency results:

out = ctx.actions.declare_file(ctx.label.name + "_unused_deps.json")

For arguments, instead of building a plain list, Bazel provides ctx.actions.args():

arguments = ctx.actions.args()
arguments.add(input)
arguments.add("--output")
arguments.add(out)

One reasonable question is: why bother with Args instead of a list?

Because command lines can get huge in real builds (compilers and linkers are the classic examples). Args lets Bazel represent and expand arguments efficiently without paying the cost of building enormous Starlark lists.

arguments = [arguments]

There is way more information about this topic on the official bazel docs page.

Running the tool

To run a tool from an aspect (or a rule), the two common approaches are:

Private attribute
Toolchains

Here I use a private attribute for simplicity (I’ve covered toolchains in a previous post).

We add a private attribute by prefixing it with _:

unused_swift_deps_aspect = aspect(
    implementation = _unused_swift_deps_impl,
    attrs = {
        "_tool": attr.label(
            default = "//tools/FindUnusedSwiftDeps",
            executable = True,
            cfg = "exec",
        ),
    },
    attr_aspects = ["deps"],
)

Then we give it a default label (the tool target), mark it executable, and set cfg = "exec" so it runs on the execution platform.

Inside the implementation, you reference it as:

tool = ctx.executable._tool

At that point, you can wire it into ctx.actions.run(...) and Bazel will execute it as part of the build.

NOTE: I intentionally omited the code for the tool itself to keep the focus on starlark.

Closing thoughts

At this point it is clear how concept of aspects in bazel can be powerful. I probably won’t be writing more about aspects directly but may share some of what I wrote and found useful.

Utilizing Bazel aspect_hints rule attribute

Sun, 25 Jan 2026 12:37:47 +0100

In the last article I provided a short introduction to the concept of aspects in Bazel. To keep the series going, today I will go over the somewhat lesser-known feature aspect_hints.

What is `aspect_hints`?

In simple terms, it is an implicit attribute available on every rule that is meant to be consumed by an attached aspect, not by the rule implementation itself. This allows us to convey “hints” to aspects in a lightweight manner.

For example, we may have an aspect that we attach to swift_library to report unused deps, but for whatever reason we need a way to tell the aspect to ignore a specific dependency.

`unused_swift_deps` aspect

Below is my dummy implementation of an aspect that finds and reports unused Swift deps. It is not a real implementation, but it is enough to showcase the potential of aspect_hints.

So in my aspects.bzl I have the following:

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

UnusedSwiftDepsInfo = provider(fields = ["report_files"])

def _unused_swift_deps(target, ctx):
    labels = []

    if hasattr(ctx.rule.attr, "deps"):
        for dep in ctx.rule.attr.deps:
            if SwiftInfo in dep:
                for module in dep[SwiftInfo].direct_modules:
                    labels.append(module.name)
                    labels.append(str(dep.label))

    out = ctx.actions.declare_file("unused_deps_" + ctx.label.name + ".txt")
    ctx.actions.write(
        output = out,
        content = "\n".join(labels),
    )

    transitive_files = []
    for dep in ctx.rule.attr.deps:
        if UnusedSwiftDepsInfo in dep:
            transitive_files.append(dep[UnusedSwiftDepsInfo].report_files)

    all_files = depset(direct = [out], transitive = transitive_files)
    return [
        UnusedSwiftDepsInfo(report_files = all_files),
        DefaultInfo(files = all_files),
    ]

unused_swift_deps_aspect = aspect(
    implementation = _unused_swift_deps,
    attr_aspects = ["deps"],
)

All of the concepts in this code are explained in my previous article on aspects, so I won’t go over them again.

Writing an aspect hint

As mentioned above, now we would like the ability to instruct this aspect to ignore certain labels. The way to achieve that will feel familiar:

Create a provider
Make an implementation function
Create a rule

First we create a provider to be able to easily give a hint to our aspect:

UnusedSwiftDepsHintInfo = provider(fields = ["ignore_deps"])

Then an implementation function:

def _ignore_unused_swift_deps_hint_impl(ctx):
    return [UnusedSwiftDepsHintInfo(ignore_deps = ctx.attr.ignore_deps)]

Finally, a rule with the single job of filling the UnusedSwiftDepsHintInfo provider:

ignore_unused_swift_deps_hint = rule(
    implementation = _ignore_unused_swift_deps_hint_impl,
    attrs = {
        "ignore_deps": attr.label_list(mandatory = True),
    },
)

Reading `aspect_hints` from the aspect implementation function

Earlier I stated that aspect_hints is an implicit rule attribute that can be read from an attached aspect. Let’s go over how to do that.

In my aspect for reporting unused Swift deps, it is simply a matter of reading the attribute like any other, checking if it carries the desired provider, and then acting upon it.

Because aspect_hints is a list of labels, I will iterate over it, check if it carries UnusedSwiftDepsHintInfo, and skip writing the ignored labels to the report file:

    ignored_deps = []

    for aspect_hint in getattr(ctx.rule.attr, "aspect_hints", []):
        if UnusedSwiftDepsHintInfo in aspect_hint:
            for ignored_dep in aspect_hint[UnusedSwiftDepsHintInfo].ignore_deps:
                ignored_deps.append(ignored_dep.label)

Now that we collected labels to ignore, we just need to make sure to actually skip them when reporting:

if dep.label in ignored_deps:
    print("Ignoring {} dep".format(str(dep.label)))
    continue

And that’s it.

Applying it to the `swift_library`

Here is how my BUILD.bazel looks when the newly created aspect hint is applied:

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

ignore_unused_swift_deps_hint(
    name = "ignore_deps_hint",
    ignore_deps = [":lib2"],
)

swift_library(
    name = "lib",
    srcs = ["main.swift"],
    aspect_hints = [":ignore_deps_hint"],
    deps = [":lib2"],
)

swift_library(
    name = "lib2",
    srcs = ["main.swift"],
    deps = [":lib3"],
)

swift_library(
    name = "lib3",
    srcs = ["main.swift"],
    module_name = "CustomModuleName",
)

And if we build:

bazel build :lib --aspects aspects.bzl%unused_swift_deps_aspect

We see that our lib2 dep is being ignored:

DEBUG: /Users/adincebic/developer.noindex/applying-aspects/aspects.bzl:30:30: Ignoring [@@](https://micro.blog/@)//:lib2 dep
INFO: Analyzed target //:lib (1 packages loaded, 5 targets configured, 5 aspect applications).
INFO: Found 1 target...
INFO: Elapsed time: 0.110s, Critical Path: 0.00s
INFO: 2 processes: 9 action cache hit, 2 internal.
INFO: Build completed successfully, 2 total actions

And of course, if we inspect bazel-bin/unused_deps_lib.txt, the file is empty.

Wrapping up

aspect_hints is a relatively simple idea that allows us to achieve powerful things. I kept the example intentionally simple, but feel free to explore widely used rulesets that rely on aspect_hints, like rules_swift for interoperability with C and other languages.

Introduction to aspects in Bazel

Sun, 18 Jan 2026 10:09:10 +0100

Bazel’s way of attaching additional information and behavior to the build graph is called aspects. They allow us to add extra logic to rules without modifying the rule implementations themselves. Common use cases include validation actions or analysis tasks such as detecting unused dependencies. These are just a few examples; aspects enable much more complex workflows.

A note on using aspects

Earlier, I mentioned that aspects allow us to attach additional logic to rules without modifying rule code. This is true, but only in one of the two ways aspects can be used:

Command-line invocation – aspects are applied externally at build time. This is what we will focus on in this article.
Attribute attachment – aspects are attached directly to rule attributes, which requires modifying the rule definition. This approach will be covered in the next article.

Writing aspects

Like most things in Bazel, aspects are rule-like and generally follow this pattern:

Write an implementation function that accepts two arguments: target and ctx
Optionally execute actions
Return providers
Create the aspect by calling the aspect() function and passing the implementation and configuration arguments

In this example, we will write an aspect that operates on swift_library targets (specifically, anything that propagates the SwiftInfo provider). The aspect will generate a .txt file containing the names of the Swift modules that the target depends on.

Given the following target:

swift_library(
    name = "lib",
    deps = [":lib2"],
    srcs = glob(["*.swift"]),
)

When the aspect is applied to this target, it will produce a text file containing lib2.

Loading required providers

In aspects.bzl, we first load the SwiftInfo provider from rules_swift:

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

Next, we define our own provider to propagate the generated report files transitively:

SwiftDepsInfo = provider(fields = ["report_files"])

Aspect implementation

Now we can write the implementation function:

def _swift_deps(target, ctx):
    module_names = []

    if hasattr(ctx.rule.attr, "deps"):
        for dep in ctx.rule.attr.deps:
            if SwiftInfo in dep:
                for module in dep[SwiftInfo].direct_modules:
                    module_names.append(module.name)

    out = ctx.actions.declare_file("swift_deps_" + ctx.label.name + ".txt")
    ctx.actions.write(
        output = out,
        content = "\n".join(module_names),
    )

    transitive_files = []
    if hasattr(ctx.rule.attr, "deps"):
        for dep in ctx.rule.attr.deps:
            if SwiftDepsInfo in dep:
                transitive_files.append(dep[SwiftDepsInfo].report_files)

    all_files = depset(direct = [out], transitive = transitive_files)
    return [
        SwiftDepsInfo(report_files = all_files),
        DefaultInfo(files = all_files),
    ]

So the code above does few simple things:

Collects Swift module names from the deps attribute via the SwiftInfo provider
Declares an output file and writes the module names into it
Collects transitive report files so they materialize as build artifacts
Returns both a custom provider (SwiftDepsInfo) and DefaultInfo

Creating the aspect

The final step is to define the aspect itself:

swift_deps_aspect = aspect(
    implementation = _swift_deps,
    attr_aspects = ["deps"],
)

Note: The attr_aspects = ["deps"] argument tells Bazel to propagate this aspect along the deps attribute. In other words, when the aspect is applied to a rule, Bazel will also apply it to every target listed in that rule’s deps.

Running the aspect

Given the following BUILD.bazel file:

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

swift_library(
    name = "lib",
    srcs = ["main.swift"],
    deps = [":lib2"],
)

swift_library(
    name = "lib2",
    srcs = ["main.swift"],
    deps = [":lib3"],
)

swift_library(
    name = "lib3",
    srcs = ["main.swift"],
    module_name = "CustomModule",
)

Running:

bazel build :lib --aspects aspects.bzl%swift_deps_aspect

will produce three additional text files which you can locate under bazel-bin/:

swift_deps_lib.txt – contains lib2
swift_deps_lib2.txt – contains CustomModule
swift_deps_lib3.txt – empty, since it has no dependencies

Why does swift_deps_lib2.txt contain CustomModule instead of lib3? Because we are explicitly extracting the Swift module name from the SwiftInfo provider. If instead we wanted the target name, we could use dep.label.name, or str(dep.label) to get the fully qualified Bazel label.

Going further

This article was a brief introduction to Bazel aspects, intended to set the foundation for the next one. In the next article, we will look at more concrete use cases and explore attaching aspects directly to rule attributes from Starlark as well as utilizing some of the other arguments on that aspect() function.

Bazel toolchains, repository rules and module extensions

Sun, 11 Jan 2026 14:23:41 +0100

In my previous article I showed how to create a stupidly simple Bazel rule. While that rule was not useful in any way, shape, or form, it provided a gentle introduction to writing Bazel rules and helped build a mental model around them.

This week we will look at toolchains, which is a more advanced concept but becomes extremely important once your rules depend on external tools.

This walkthrough wires up macOS only to keep the example small. Adding Linux or Windows is the same pattern: download a different binary and register another toolchain(...) target with different compatibility constraints.

Toolchains

A Bazel toolchain is a way of abstracting tools away from rules. Many people describe it as dependency injection.

More precisely: toolchains are dependency injection with platform-based resolution — Bazel selects the right implementation based on the execution and target platforms.

Instead of hard-coding a tool inside a rule, the rule asks Bazel to give it “the correct tool for this platform”.

Example: `rules_pkl`

We will create oversimplified rule called pkl_library that turns .pkl files into their JSON representation using the PKL compiler. pkl is Apple’s programing language for producing configurations. There is official rules_pkl ruleset and this article doesn’t even scratch the surface of the capabilities that it offers.

To do this we need:

A way to download the PKL binary
A toolchain
A rule that uses the toolchain

Downloading the PKL binary

We start by writing a repository rule that downloads the PKL compiler and exposes it as a Bazel target.

Create repositories.bzl:

def _pkl_download_impl(repository_ctx):
    repository_ctx.download(
        url = repository_ctx.attr.url,
        output = "pkl_bin",
        executable = True,
        sha256 = repository_ctx.attr.sha256,
    )

    repository_ctx.file(
        "BUILD.bazel",
        """
load("@bazel_skylib//rules:native_binary.bzl", "native_binary")

native_binary(
    name = "pkl",
    src = "pkl_bin",
    out = "pkl",
    visibility = ["//visibility:public"],
)
""",
    )

pkl_download = repository_rule(
    implementation = _pkl_download_impl,
    attrs = {
        "url": attr.string(mandatory = True),
        "sha256": attr.string(mandatory = True),
    },
)
````

This does two things:

* Downloads the PKL binary
* Wraps it using `native_binary`, which creates a proper Bazel executable without relying on a shell

The resulting binary is available as `@pkl_macos//:pkl`.

## Exposing the repository via a module extension

We’re still using a [repository rule](https://bazel.build/external/repo) to do the download; [bzlmod module extensions](https://bazel.build/external/extension) are just how we call that repository rule from `MODULE.bazel`.

Create `extensions.bzl`:

```starlark
load("//:repositories.bzl", "pkl_download")

def _pkl_module_extension_impl(ctx):
    pkl_download(
        name = "pkl_macos",
        url = "https://github.com/apple/pkl/releases/download/0.30.2/pkl-macos-aarch64",
        sha256 = "75ca92e3eee7746e22b0f8a55bf1ee5c3ea0a78eec14586cd5618a9195707d5c",
    )

pkl_extension = module_extension(
    implementation = _pkl_module_extension_impl,
)

In MODULE.bazel:

bazel_dep(name = "platforms", version = "1.0.0")
bazel_dep(name = "bazel_skylib", version = "1.9.0")

pkl_extension = use_extension("//:extensions.bzl", "pkl_extension")
use_repo(pkl_extension, "pkl_macos")

Now the binary can be referenced as @pkl_macos//:pkl.

Creating the toolchain

A toolchain is just a rule that returns a ToolchainInfo provider.

toolchains.bzl:

def _pkl_toolchain_impl(ctx):
    return [platform_common.ToolchainInfo(
        pkl_binary = ctx.executable.pkl_binary,
    )]

pkl_toolchain = rule(
    implementation = _pkl_toolchain_impl,
    attrs = {
        "pkl_binary": attr.label(
            executable = True,
            cfg = "exec",
            allow_files = True,
            mandatory = True,
        ),
    },
)

The important part is cfg = "exec", which ensures the binary runs on the execution platform.

registering the toolchain

In BUILD.bazel:

load("//:toolchains.bzl", "pkl_toolchain")

toolchain_type(
    name = "pkl_toolchain_type",
    visibility = ["//visibility:public"],
)

pkl_toolchain(
    name = "pkl_toolchain_macos_impl",
    pkl_binary = "@pkl_macos//:pkl",
)

toolchain(
    name = "pkl_toolchain_macos",
    toolchain = ":pkl_toolchain_macos_impl",
    toolchain_type = ":pkl_toolchain_type",
    exec_compatible_with = ["@platforms//os:macos"],
    target_compatible_with = ["@platforms//os:macos"],
)

To register the toolchain we need to modify our MODULE.bazel:

register_toolchains("//:pkl_toolchain")

Using the toolchain in a rule

Now we can write pkl_library.

Create rules.bzl:

def _pkl_library_impl(ctx):
    toolchain = ctx.toolchains["//:pkl_toolchain_type"]
    binary = toolchain.pkl_binary

    compiled_files = []
    for src in ctx.files.srcs:
        compiled_file_name = src.basename.replace(".pkl", ".json")
        compiled_file = ctx.actions.declare_file(compiled_file_name)

        ctx.actions.run(
            executable = binary,
            tools = [binary],
            inputs = [src],
            outputs = [compiled_file],
            arguments = [
                "eval",
                src.path,
                "--format",
                "json",
                "-o",
                compiled_file.path,
            ],
            mnemonic = "PKLCompile",
        )

        compiled_files.append(compiled_file)

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

pkl_library = rule(
    implementation = _pkl_library_impl,
    attrs = {
        "srcs": attr.label_list(
            allow_files = [".pkl"],
            mandatory = True,
        ),
    },
    toolchains = ["//:pkl_toolchain_type"],
)

The rule never knows which concrete PKL binary is being used — it only sees the resolved toolchain.

NOTE: Here instead of writing a for loop that creates new action per file is a decision that we need to make on a case by case basis. Sometimes it can be faster to run multiple actions in parallel than invoking a tool once and giving it a list of files to process. It heavily depends on the tool itself and shows us how bazel can be powerful in these scenarios.

Final thoughts

This was a practical look at repository rules, module extensions, toolchains, and how they fit together.

Toolchains are one of Bazel’s most powerful features. Once you start writing rules that depend on real tools (compilers, linters, generators), this pattern becomes unavoidable.

This marks the completion of my second article where I try to give real world examples of using bazel’s various features.

Writing a simple bazel rule

Sun, 04 Jan 2026 19:51:46 +0100

This article does not get into what the Bazel build system is or why you might consider using it. Instead, it focuses on explaining, in very simple terms, how to write a Bazel rule.

First things first

You need a Bazel repository, often referred to as a workspace. To create one, you need a MODULE.bazel file at the root of your project. This file is used to declare external dependencies, although that is not its only purpose. For now, let’s keep MODULE.bazel empty.

Next is a BUILD.bazel file. This is where rules are instantiated (used). The result of instantiating a rule is a Bazel target. Create an empty BUILD.bazel file at the root of the project as well.

Writing the rule

Think of a Bazel rule as a way to teach Bazel how to produce something. We will start by producing a simple text file and then make it slightly more complex.

We will call this rule hello. It will produce a file named hello.txt containing the word "hello".

Create a file called hello.bzl with the following content:

def _hello_impl(ctx):
    file = ctx.actions.declare_file(ctx.label.name + ".txt")
    ctx.actions.write(
        output = file,
        content = "hello",
    )
    return DefaultInfo(files = depset([file]))

This function is the implementation of our hello rule. Notice that the function name ends with _impl. This is a common Bazel convention for rule implementation functions, although it is not strictly required.

The function takes a single parameter, ctx. Every rule implementation receives a ctx (context) object, which provides access to attributes, labels, and the actions API used to interact with Bazel.

Before creating an action, we declare the output file:

file = ctx.actions.declare_file(ctx.label.name + ".txt")

This tells Bazel that the rule will produce a file named after the target (hello.txt in our case). The returned file object represents a declared output that can be passed to actions.

Next, we create an action that writes content to the file:

ctx.actions.write(
    output = file,
    content = "hello",
)

Here we explicitly tell Bazel what the output of the action is. Being explicit about outputs (and inputs, when present) is a defining characteristic of Bazel’s build model. In this example, there are no inputs—only an output.

Finally, we return a result from the rule using the DefaultInfo provider:

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

This makes the produced file part of the target’s default outputs. We will not go into providers or depset in this article; the official documentation covers those topics in depth.

Now that the implementation function exists, we define the rule itself by calling rule():

hello = rule(
    implementation = _hello_impl,
)

This is enough to define a usable rule.

Using the rule

In the previously created BUILD.bazel file, we first load the rule:

load(":hello.bzl", "hello")

Then we instantiate it:

hello(
    name = "hello",
)

Now run:

bazel build :hello

You should see output similar to:

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

Pay attention to the line bazel-bin/hello.txt. This is where Bazel exposes the output file (typically via a symlink). Open it with:

open bazel-bin/hello.txt

You should see that the file contains the word hello.

Rule attributes

To make this rule somewhat useful, we will add a new attribute called content that replaces the hardcoded "hello" string.

The first step is to declare that our rule has an attribute named content. We do this by providing a dictionary to the attrs parameter of rule():

hello = rule(
    implementation = _hello_impl,
    attrs = {
        "content": attr.string(mandatory = True),
    },
)

Here we declare a mandatory string attribute named content. Bazel will enforce that this attribute is provided when the rule is instantiated.

Next, we read the value of the attribute in the rule implementation function. Rule attributes are accessible through ctx.attr. We replace the hardcoded value with ctx.attr.content:

def _hello_impl(ctx):
    file = ctx.actions.declare_file(ctx.label.name + ".txt")
    ctx.actions.write(
        output = file,
        content = ctx.attr.content,
    )
    return DefaultInfo(files = depset([file]))

Finally, we provide the attribute value when instantiating the rule in the BUILD.bazel file:

hello(
    name = "hello",
    content = "Hello, world!",
)

After running:

bazel build :hello

the file located at bazel-bin/hello.txt will contain the provided text.

That’s it

This concludes my first article on the Bazel build system. I plan to expand this rule in subsequent articles to demonstrate more advanced concepts and gradually make it more useful. This also marks my first article of the year, and I plan to write one technical article every week until the year 2026 concludes.

Reverse Engineering Apple's on-demand resource Asset Packs: How to Recreate .assetpack Files with Standard Unix Tools

Mon, 18 Aug 2025 14:36:33 +0100

I recently ran into a problem while integrating Apple’s on-demand resources system to bazel. Essentially I needed a way to generate .assetpack archives via command line without calling into xcodebuild.

After spending way too much time debugging this, I finally figured out exactly what Apple’s toolchain does to create these files - and more importantly, how to recreate them using standard macOS command-line tools.

The Problem: Asset Packs Look Like Regular Zip Files (But Aren’t)

When you run file on an .assetpack, it tells you it’s a zip archive:

$ file my-assets.assetpack
my-assets.assetpack: Zip archive data

So naturally I thought I will create the expected file hierarchy and zip it:

zip -r new-assets.assetpack some-assetpack-folder/

Your asset pack becomes unusable. iOS will reject it, and you’ll get unhelpful errors about not being able to move the file to the NSBundle.

Investigating the Differences

I used zipinfo -v to examine the internal structure of both Apple’s original asset packs and my re-zipped versions:

Apple’s Original Asset Pack: - Compression: none (stored) - zero compression - File ordering: Very specific sequence starting with META-INF/ - Structure: Flat hierarchy with files at zip root level - Metadata: No extended attributes or extra fields - Encoding version: 3.0

My zipped Version: - Compression: deflated - standard compression - File ordering: Alphabetical (zip’s default) - Structure: Nested bundle directory structure - Metadata: Full of Unix extended attributes and timestamps - Encoding version: 2.0

The Critical Requirements

After lots of experimentation, I discovered Apple’s asset packs have five strict requirements:

1. Flat Hierarchy Structure

The contents must be at the zip root level, not nested in a bundle directory. Apple’s structure looks like:

META-INF/
_CodeSignature/
SomeFile
Info.plist

Not like:

com.company.app.bundle-hash/
├── META-INF/
├── _CodeSignature/
├── SomeFile
└── Info.plist

2. Zero Compression

Every single file must use the store method (no compression). This is critical - any compressed files will cause rejection.

3. Specific File Ordering

The central directory must have entries in this exact order: 1. META-INF/ (directory) 2. META-INF/com.apple.ZipMetadata.plist (file) 3. _CodeSignature/ (directory) 4. Code signature files 5. Content files 6. Info.plist

4. No Extended Attributes

The zip must be clean of any extended attributes, Unix UID/GID info, or extra metadata fields.

5. The Critical Metadata File

The META-INF/com.apple.ZipMetadata.plist file must be the second entry in the zip. This file contains metadata that iOS validates.

The Solution: Recreating Asset Packs Correctly

Here’s the call to zip that packages the assetpack correctly:


# Navigate to the assetpack directory
cd some-assetpack-directory/

# Recreate with proper ordering and settings
(echo "META-INF/"; echo "META-INF/com.apple.ZipMetadata.plist"; find . -mindepth 1 -not -path "./META-INF*") | zip -0 -X recreated.assetpack -@

Let me break down what each part does:

echo "META-INF/" - Ensures META-INF directory is first
echo "META-INF/com.apple.ZipMetadata.plist" - Puts the critical metadata file second
find . -mindepth 1 -not -path "./META-INF*" - Adds everything else while excluding META-INF (to avoid duplicates)
zip -0 -X ... -@ - Creates zip with zero compression (-0), no extended attributes (-X), reading file list from stdin (-@)

The Bottom Line

Apple’s asset packs aren’t just zip files - they’re zip files with very specific structural requirements. iOS validates not just the content, but the exact structure, compression settings, and file ordering of the archive.

With the right zip parameters and file ordering, it is very easy to create them.

Integrating Conan with Xcode to manage C/C++ libraries

Sat, 23 Sep 2023 08:11:59 +0100

In my last post I went over how to manually link C++ libraries to Xcode project. While that is useful to know, it gets tedious to maintain once you have multiple C++ dependencies. In addition, if the library you want to link does not come with built binary, you are responsible for that too which in some cases may not be fun at all.

Enter Conan

Conan is a package manager for C/C++ that in addition to getting libraries, it allows for easy building of libraries for various CPU architectures which I personally find incredibly useful.

Why?

Past few weeks I spent some time building cross-platform library using C++ for iOS and Android which ended up depending on Crypto++. This meant that besides building the Crypto++ from source for iOS and iOS simulator, now I needed to build it for four more architectures (armV7, armV8), x86 and x86_64) that Android runs on.

Integrating Conan with Xcode

First things first, you need to make sure that you have Conan installed. The easiest way is with Homebrew, simply open terminal and run brew install conan. Once that’s sorted out, change directory to where your Xcode project is and create new “conanfile.txt” file. Make sure that it contains the following:

[requires]
cryptopp/8.8.0
[generators]
XcodeDeps
XcodeToolchain
[layout]
cmake_layout

this sets up Conan to look for 8.8.0 version of Crypto++. Then in the “generators” section of the file it tells Conan to generate xcconfig files that will ultimately help us link the library.

Next, it is required to create a Conan profile that describes how to build the library. It contains information like which CPU architecture to build for, whether to build in debug or release mode etc. So still in directory where your Xcode project is, go ahead and create empty file and give it “simulator-profile” name. You can pick whatever name you like, this is just my preference. After that, it should contain the following:

[settings]
arch=armv8
build_type=Debug
compiler=apple-clang
compiler.cppstd=gnu17
compiler.libcxx=libc++
compiler.version=15
os=iOS
os.version=17.0
os.sdk=iphonesimulator

this is pretty self-explanatory. It tells Conan to build the library for armV8 architecture using Clang version 15 and it tells what is the minimum iOs deployment target in addition to which SDK to build for.

Building and linking

After installing Conan, setting up “conanfile.txt” and “simulator-profile” it is time to build. Make sure your working directory in the terminal is the one that contains “conanfile.txt” and run

conan install . --build=missing --profile=simulator-profile --output-folder=conan-generated

Here is the breakdown of the entire command:

conan install . runs “install” command from conan. The “.” is used to look for “conanfile.txt” in the current working directory.
--build=missing explicitly tells Conan that the build for the library is missing which makes it build the library from source, hence the word “missing”.
--profile=simulator-profile this is passing profile file that I created earlier.
--output-folder=conan-generated this is the directory where Conan will generate files using generators I specified in “conanfile.txt”. I named it “conan-generated” but you can name that whatever you like, popular one is “build”.

So after command ran, you should see “conan-generated” directory next to your other project files. I recommend adding “conan-generated/” to .gitignore. All that’s left is to open your Xcode project and add “conan_config.xcconfig” file that is in “conan-generated” directory. I won’t go into specifics of using config files in Xcode, there is plenty of articles about that, like the one from NSHipster. It’s important to note that XcodeDeps aggregates all files and settings. Therefore, running the command above multiple times is not only acceptable but also necessary if you want it to generate configurations for all cases. For example if you want to have library linked both for simulator and device in debug and release configurations, you should run the command with different parameters multiple times.

Closing words

Even though there is a bit of learning curve and setup when it comes to Conan, it makes our lives much easier. Once you grasp the concepts you realize that integration between Conan and Xcode is fundamentally very simple. To deepen your understanding of Conan and its generators, it is best to consult official Conan documentation page. And to explore the vast universe of C/C++ libraries available for use with Conan, Conan center is the best place for that.

Linking C++ static library in iOS project

Sun, 03 Sep 2023 14:17:05 +0100

Linking against a static C++ library in Xcode tends to get complicated. Even though the idea is simple, there are few traps that you can run into.

The idea

Write C++ code.
Write interface which will be usable from Objective-C and Swift.
Package it as a static “.a” library.
Link it to iOS app project.

Let’s start with simple C++ code

We will create a class named ExampleCode which will expose single function helloWorld() that returns static string.

    #ifndef ExampleCode_hpp
    #define ExampleCode_hpp

    #include <stdio.h>

    using namespace std;

    class ExampleCode {
    public:
        const char* helloWorld();
    };

    #endif /* ExampleCode_hpp */

And here is the implementation:

    #include "ExampleCode.hpp"

    const char* ExampleCode::helloWorld() {
        char const *str = "This is my library";
        return str;
    }

Creating interface for Objective-C and Swift

Because Swift still doesn’t have interoperability with C++, we need to utilize Objective-C++ to achieve our goal of using the library from Swift. In the same project for our dummy library, create a new Objective-C file with header:

#import <Foundation/Foundation.h>

@interface NewLibrary : NSObject
- (NSString*)hello;
@end

Now for the implementation file it is important to change its .m extension to .mm because that is what makes it tap into C++ (aka makes it Objective-C++).

#import "NewLibrary.h"
#import "ExampleCode.hpp"

@implementation NewLibrary
- (NSString *)hello {
    ExampleCode* example = new ExampleCode();
    NSString* str = [NSString stringWithUTF8String:example->helloWorld()];
    return str;
}
@end

Also remember ExampleCode.hpp is the C++ header file that I created above, so that is why I import it here.

Packaging this code as static C++ .a library

This is fairly simple stuff, but here are the steps:

Set your scheme to Release configuration.
Build both for “Any iOS Simulator Device (arm64, x86_64)” and for “Any iOS Device (arm64)”. No, you can’t do it both at once.
Find your build products in Xcode’s derived data folder. You should see two folders “Release-iphonesimulator” and “Release-iphoneos”. In there there is your “.a” library file and “include” folder containing “.h” header Objective-C file that we created earlier.

Now, most of the old advice goes to say that you should use lipo command to create universal (fat) binary. However this will only get you in trouble. Firstly, if you try creating universal binary from simulator and iOS device “.a” library files you will get an error telling you that both files are built for arm64 architecture. That is because they actually are since Apple Silicon was introduced. Secondly, don’t try to remove arm64 architecture from simulator “.a” library using lipo -remove arm64 path-to-simulator-lib.a -output library.a, not because it won’t work but because it will create troubles when debugging on simulator later on. Actually, you don’t need to do anything with those files at this point.

Linking against your library in separate iOS project

So in a new iOS project in Xcode it is required to perform a couple of steps to link your newly created static C++ library:

Before you add your “.a” files into iOs project, it would be helpful to rename them such that you can differentiate simulator from real device “.a” libraries because they are different. You can name them something like NewLibrary-sim.a and NewLibrary-device.a.
Add your “.a” files to Xcode project. Make sure that you check the box “Copy files if needed” when dropping “.a” files. Also make sure that you don’t add them to your target because we will link them conditionally in later step.
Add “.h” header file. Just because you have two “.a” files, you don’t need two header files. Also make sure that you check “Copy files if needed” when dropping it into your project.
In project build settings look for “other linker flags” and next to Debug and Release configurations click + icon and add two new entries, one for the simulator SDK and the other for the iOS SDK. In the entry for simulator SDK add path to your simulator .a file, you can write it like this $(SRCROOT)/Libraries/NewLibrary-sim.a. $(SRCROOT) gives you the path to the root of your project. And repeat the same for iOS SDK $(SRCROOT)/Libraries/NewLibrary-device.a.
Now for the library to work, you also need to link against C++ standard library. Fortunately it is pretty straight forward. Go to build phases for your target and add “libc++.tbd” under “Link Binary With Libraries”. This is very important step and one that I see so many other articles fail to mention.
Finally, because interface for our library is written in Objective-C, wee need to create bridging header. You can do that manually or you can add empty Objective-C file to your project and Xcode will offer to create bridging header for you. What ever you choose, just make sure to import your library header in bridging header to make Swift recognize public interface for your library.

//
//  Use this file to import your target's public headers that you would like to expose to Swift.
//

#import "NewLibrary.h"

At this point you should be able to build the app either for simulator or device without any issues.

Things to keep in mind

Swift will get support for direct interoperability with C++ very soon. It actually already supports it but the current stable Xcode version still does not ship Swift 5.9. This means that Objective-C won’t be necessary anymore.
Don’t fall into traps with removing arm64 from simulator version of your library. Also don’t go into build settings and add arm64 to “Excluded architectures”. If you do so, simulator will utilize Rosetta to run your app and debugging experience gets a lot slower and simulator starts to freeze.

Conclusion

Utilizing language like C++ can be very beneficial as it allows for code sharing between different platforms. However it can get challenging if you are doing it for the first time or you fail to perform one of the steps outlined in this article.

Introducing the existentialannotator: A Swift Command Line Tool that automatically marks all existential types with

Sun, 30 Jul 2023 18:14:23 +0100

I am pleased to present my command line tool that I hacked together on a Saturday morning, the “existentialannotator,” which can be found on github. As the name suggests, this tool performs a specific function: scanning your Swift files, identifying all declared protocols, and annotating all existential types with any. This feature will prove invaluable with the upcoming release of Swift 6. To get started, you have two options: installing it via Homebrew or obtaining the source code directly from GitHub and building it yourself. Once installed, simply navigate to your working directory and execute the command existentialannotator . to let the tool do its job.

Background

Concept of existential types in Swift has not been heavily discussed topic until recently when it was introduced as part of the Swift Evolution process on GitHub. Essentially, an existential type represents the existence of any specific type without specifying that particular type explicitly. This means that certain code, like the example below, will not compile in Swift 6:

protocol Vehicle {
  var batteryPercentage: Float { get }
}

struct HumanDriver {
  let vehicle: Vehicle

  func drive() {
    // Drive the vehicle
  }
}

The compilation fails because let vehicle: Vehicle utilizes an existential type without being explicitly annotated with the new keyword any.

Understanding Existential Types

In Swift, an existential type provides a way to handle values of different types in a unified manner, abstracting their specific type information. In the example above, we used the protocol Vehicle instead of a concrete type, demonstrating the essence of an existential type.

What’s New in Swift 6?

In Swift 6, every existential type must be marked with any. Failure to do so will result in a compilation error. Consequently, the code above let vehicle: Vehicle would now require the notation let vehicle: any Vehicle. This is where my tool, the Existential Annotator, comes in handy, particularly when dealing with large codebases.

Final Remarks

Although I put this tool together on Saturday morning, it is not flawless. There are numerous potential performance improvements that could be implemented. Nonetheless, I consider this tool complete, given its limited lifespan. As we move past the initial release of Swift 6, this tool will likely lose its relevance. Nevertheless, if you believe it could benefit from enhancements, please feel free to submit a pull request.

Using Swift withCheckedThrowingContinuation in methods without return value

Mon, 08 Aug 2022 17:05:00 +0100

When refactoring old closure-based code to new Swift concurrency it is inevitable that you come accross scenario where you need to call withCheckedThrowingContinuation where enclosing method has no return value. In that case, you should get error in Xcode: Generic parameter ’T’ could not be inferred

Let’s consider the following block of code

func fetchData() async throws {
    try await withCheckedThrowingContinuation({ continuation in
        URLSession.shared.dataTask(with: URL(string: "https://example.com")!) { data, response, error in
            if let error = error {
                continuation.resume(throwing: error)
                return
            }
            continuation.resume()
        }.resume()
    })
}

This code produces the error above because withCheckedThrowingContinuation method has generic parameter which compiler usuallly infers from return value of enclosing method. However, our enclosing method fetchData has no return value thus compiler raises the error.

Fortunately the fix is incredibly simple, just cast return type to Void

func fetchData() async throws {
    try await withCheckedThrowingContinuation({ continuation in
        URLSession.shared.dataTask(with: URL(string: "https://example.com")!) { data, response, error in
            if let error = error {
                continuation.resume(throwing: error)
                return
            }
            continuation.resume()
        }.resume()
    }) as Void
}

It is important to note that this approach works for all methods not just for withCheckedThrowingContinuation or other methods specific to Swift concurrency.

How to check if Xcode is building for previews

Mon, 28 Mar 2022 11:11:28 +0100

Lately, I find myself often dealing with a lot of Xcode build phases. One common problem that I encounter is that SwiftUI previews won’t work if some build phase runs a script which messes with Xcode project file or with individual files. For example, script which sorts files alphabetically may modify Xcode project file which will prevent previews to work. To work around this problem, you can check if Xcode is building for previews and then decide whether to run the script or not.

if [ ${ENABLE_PREVIEWS} == NO ];
then
echo "Running sorting script"
fi

Adin Ćebić

A Practical Introduction to Bazel Persistent Workers

Creating a rule that leverages workers

An uppercase rule

Creating a rule

The Swift worker

Trying out the rule

Building and verifying

A few notes

Conclusion

Why My Xcode Extension Kept Asking for File Permissions

The mistake

Conclusion

Centralizing Dependency Fetching in Bazel with the Remote Asset API

Bazel Remote Asset API

How to Use

A Note on the Experimental Flag

Conclusion

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

Introducing repo.bazel

Conclusion

Reconfiguring bazel downloader

Bazel downloader config

File structure and syntax

Rewrite directive

Evaluation order

Comments

Conclusion

Bazel Output Groups: Producing Outputs on Demand

Enter output groups

Smallest possible example

Requesting the debug output

Conclusion

What Bazel Really Runs (and How to See It)

Action graph query

Doing something useful

Making it executable

Conclusion

Bazel split transitions

Multi-arch build

Multi-platform Swift library

Conclusion

How to Fix Xcode Source Editor Extensions That Don’t Appear in the Editor Menu

Extension not showing up in Xcode

Asking around

Sifting through Xcode logs

Looking at existing extensions

Missing XcodeKit.framework

The fix: Embed without signing

Closing thoughts

Managing Bazel Flags in Monorepos with Flagsets (PROJECT.scl)

Current state of the art

The solution

Example iOS app

Enforcement policies

Target-specific flags

In conclusion

Composing Bazel rules with subrules

Subrules

Important: Subrules Must Be Declared

What You Can and Cannot Do

All Attributes Must Be Private

Attributes Must Be label or label_list

Private attributes Require Defaults

The Context Is Restricted

Toolchains and Execution Groups

Nested Subrules

Why Subrules Matter

Takeaways

Applying Bazel Transitions to Third-Party Rules the Right Way

Enter Rule Extensions

A Simple Transition

Applying the Transition

Wrapping Up

Creating Custom Command-Line Flags in Bazel

Build Settings

Pre-defined Settings

Creating a Flag

Reacting to Build Settings

Using select()

Introducing `repo.bazel`

Missing `XcodeKit.framework`

Using `select()`

What is `aspect_hints`?

`unused_swift_deps` aspect

Reading `aspect_hints` from the aspect implementation function

Applying it to the `swift_library`

Example: `rules_pkl`