CHANGELOG.md

+# [1.0.0-alpha.5](https://git.gitlab.arm.com/bazel/ape/compare/v1.0.0-alpha.4...v1.0.0-alpha.5) (2024-02-24)
+
+### Bug Fixes
+
+- register toolchains for supported platforms ([3788301](https://git.gitlab.arm.com/bazel/ape/commit/3788301606765c37ad6f22ebb01d86168319d355))
+
+### Features
+
+- add `ape_toolchain` macro ([e89d679](https://git.gitlab.arm.com/bazel/ape/commit/e89d679e18822f90ac64f14479932b0477ee8239))
+
 # [1.0.0-alpha.4](https://git.gitlab.arm.com/bazel/ape/compare/v1.0.0-alpha.3...v1.0.0-alpha.4) (2024-02-22)
 
 ### Bug Fixes

MODULE.bazel

 module(
     name = "ape",
-    version = "1.0.0-alpha.4",
+    version = "1.0.0-alpha.5",
     bazel_compatibility = [
         ">=7.0.0",
     ],
@@ -9,7 +9,7 @@ module(
 
 bazel_dep(name = "rules_curl", version = "1.0.0-alpha.6", dev_dependency = True)
 
-bazel_dep(name = "toolchain_utils", version = "1.0.0-beta.1")
+bazel_dep(name = "toolchain_utils", version = "1.0.0-beta.3")
 bazel_dep(name = "download_utils", version = "1.0.0-beta.1")
 
 download_archive = use_repo_rule("@download_utils//download/archive:defs.bzl", "download_archive")

README.md

@@ -22,6 +22,22 @@ List the available executables:
 bazel query 'kind(alias, @ape//:*)'
 ```
 
+Register a binary as a toolchain for [supported platforms][supported-platforms][^1]:
+
+```py
+load("@ape//ape/toolchain:defs.bzl", "ape_toolchain")
+
+toolchain_type(
+    name = "type",
+)
+
+ape_toolchain(
+    name = "ape",
+    toolchain = "@ape//:curl",
+    toolchain_type = ":type",
+)
+```
+
 ## Hermeticity
 
 The module is fully hermetic, all binaries are downloaded and verified against subresource integrities.
@@ -34,6 +50,17 @@ Cosmopolitan binaries work across all operating systems as explained [upstream][
 
 Binaries are built with [superconfigure].
 
+The [superconfigure] source code is mirrored in this repository on the [`superconfigure/main`][mirror] branch. The source contains the source code for the binaries, patches and license information.
+
+Binaries are mirrored in the [GitLab generic package registry][package-registry] to protect against upstream outages.
+
+---
+
 [cosmo.zip]: https://cosmo.zip
 [ape]: https://justine.lol/ape.html
 [superconfigure]: https://github.com/ahgamut/superconfigure
+[package-registry]: https://gitlab.arm.com/bazel/ape/-/packages
+[mirror]: https://gitlab.arm.com/bazel/ape/-/tree/superconfigure/main
+[supported-platforms]: https://github.com/jart/cosmopolitan/wiki/Features#systems-and-cpu-arch-supported
+[^1]: Apple silicon is supported upstream but currently unsupported by this ruleset, see #1
+

ape/toolchain/defs.bzl

+load(":macro.bzl", _toolchain = "toolchain")
+
+visibility("public")
+
+ape_toolchain = _toolchain

ape/toolchain/macro.bzl

+visibility("//...")
+
+def toolchain(*, name, toolchain, toolchain_type, target_compatible_with = None):
+    """
+    Registers an αcτµαlly pδrταblε εxεcµταblε (APE) binary as a Bazel toolchain.
+
+    Only registers the APE binary for platform constraints that are known to work.
+
+    ```py
+    load("@ape//ape/toolchain:defs.bzl", "ape_toolchain")
+
+    toolchain_type(
+        name = "type",
+    )
+
+    ape_toolchain(
+        name = "ape",
+        toolchain = "@ape//:curl",
+        toolchain_type = ":type",
+    )
+    ```
+    """
+    toolchain = native.package_relative_label(toolchain)
+    toolchain_type = native.package_relative_label(toolchain_type)
+
+    [
+        native.toolchain(
+            name = "{}-{}-{}".format(name, cpu, os),
+            toolchain = toolchain,
+            toolchain_type = toolchain_type,
+            exec_compatible_with = (
+                "@toolchain_utils//toolchain/constraint/cpu:{}".format(cpu),
+                "@toolchain_utils//toolchain/constraint/os:{}".format(os),
+            ),
+            target_compatible_with = target_compatible_with,
+        )
+        # https://github.com/jart/cosmopolitan/wiki/Features#systems-and-cpu-arch-supported
+        for cpu, os in (
+            ("amd64", "linux"),
+            ("amd64", "windows"),
+            ("amd64", "macos"),
+            ("amd64", "openbsd"),
+            ("amd64", "netbsd"),
+            ("amd64", "freebsd"),
+            ("arm64", "linux"),
+            # TODO: enable when we have Apple silicon launcher hooked up
+            # ("arm64", "macos"),
+            ("arm64", "freebsd"),
+        )
+    ]

e2e/MODULE.bazel

@@ -24,4 +24,4 @@ resolved(
     toolchain_type = "//toolchain/curl:type",
 )
 
-register_toolchains("//toolchain/curl:all")
+register_toolchains("//toolchain/...")

e2e/toolchain/curl/BUILD.bazel

+load("@ape//ape/toolchain:defs.bzl", "ape_toolchain")
 load("@toolchain_utils//toolchain/test:defs.bzl", "toolchain_test")
 
 toolchain_type(
@@ -5,9 +6,9 @@ toolchain_type(
     visibility = ["//visibility:public"],
 )
 
-toolchain(
+ape_toolchain(
     name = "ape",
-    toolchain = "@ape-curl//:curl",
+    toolchain = "@ape//:curl",
     toolchain_type = ":type",
 )