Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .bazelrc
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,13 @@ test --test_output=errors
# malformed response". (The Apple build requires a local Xcode anyway.)
build --strategy=SwiftCompile=local

# A Clang module cache of each Swift compile's own (until rules_swift says so
# for Android and wasm): rules_swift 4.3.0 builds those without explicit
# modules (rules_swift#1999), so their Clang modules are built implicitly,
# and in the shared cache two builds of one of the Swift SDK's modules
# conflict ("module '_Builtin_stddef' is defined in both …").
build --features=-swift.use_global_module_cache

# swift_ffi's `analyzer` / `generator` are swift.org-toolchain swift_binaries
# invoked as build actions (the analyzer aspect + ffi_generate). They need the
# Swift runtime, which the action sandbox doesn't stage — so each host resolves
Expand Down
111 changes: 60 additions & 51 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ management. The repo is ONE Bazel module, `isomer`, plus the examples:
| --- | --- | --- |
| `.` | `isomer` | everything below |
| `swift_ffi/` | (isomer) | the Swift <-> Kotlin/JavaScript/C bridge generator: macros, analyzer, generator, rules, runtimes. Labels `//swift_ffi/...` (`@isomer//swift_ffi/...` from outside). Its own examples are `swift_ffi/examples`; docs in `docs/swift_ffi/`. Every BUILD file under it carries `package(features = [swift.enable_v6, treat_warnings_as_errors, ...])` — what its REPO.bazel said when it was a repo; keep that on new packages there |
| `core_graphics/`, `foundation/` | (isomer) | Isomer's `CoreGraphics` and `Foundation` for the platforms without Apple's (see "Apple's frameworks off Apple") |
| `core_graphics/`, `foundation/` | (isomer) | Isomer's `CoreGraphics` for Linux and Windows, and Foundation's build settings and tests: Isomer's `Foundation`, and Android's and the web's CoreGraphics and Combine, are in Isomer's Swift SDKs since 0.56 (AttilaTheFun/isomer_hermetic_toolchains; see "Apple's frameworks off Apple") |
| `frameworks/` | (isomer) | the other Apple frameworks SwiftUI's interface names, off Apple: `CoreTransferable`, `UniformTypeIdentifiers`, `PhotosUI`, `OSLog` (`Logger`: logcat on Android, standard error elsewhere; `@isomer//:os_log`, and in each platform's SDK group), `Combine` (since 0.42: Isomer's own, beneath Foundation). Not UIKit or Dispatch (see "Apple's frameworks off Apple") |
| `metal/` | (isomer) | Isomer's `Metal` (`//metal/metal`), IsomerMetal (`//metal/isomer_metal`: the MSL→WGSL translator, the backend interface), the web backend (`//metal/web`, `//metal/runtime`) |
| `swift_gpu/` | (isomer) | the GPU abstraction (`//swift_gpu/{core,metal,apple,android,wasm,linux,windows}`) |
Expand All @@ -52,7 +52,7 @@ nothing under `swift_ffi/` may depend on anything outside it but Foundation,
and so on up. A consumer pins ONE version of isomer (by version from the
project's registry, AttilaTheFun/bazel_registry, from 0.36.0; a commit
between releases) and lists that registry before the BCR in its .bazelrc:
no override of isomer's dependencies since 0.40 (rules_swift 4.2.2.isomer.3
no override of isomer's dependencies since 0.40 (rules_swift 4.3.0.isomer.1
sorts above the 4.2.2 rules_applecross asks for).

**Versions (from 0.38).** A version is MAJOR.MINOR.BUILD; there are no
Expand Down Expand Up @@ -86,10 +86,10 @@ minor (MAJOR.MINOR.0) before the release's commit.
by version at a release (a commit is fine on a branch, or on main between
releases). Bazel modules come from bazel_registry, before the BCR: isomer's
releases, visor's, and the forks isomer carries until upstream takes their
changes, as patched versions (rules_swift 4.2.2.isomer.3: upstream 4.2.2
with rules_swift#1989, #1860, #1990, #1995, #1985 and #2000, each a patch
taken from the PR's head). A change to a fork or to those
patches is a new entry (.isomer.4), made with the registry's
changes, as patched versions (rules_swift 4.3.0.isomer.1: upstream 4.3.0
with rules_swift#1860, #1990, #1995 and #2000, each a patch taken from the
PR's head). A change to a fork or to those
patches is a new entry (.isomer.2), made with the registry's
tools/add_version.py --fork and approved there like any version. Swift
packages are SwiftPM's, through rules_swift_package_manager, never Bazel
modules. tools/released_pins.sh says whether every pin is a released
Expand Down Expand Up @@ -144,14 +144,19 @@ What building a whole application on the stack taught (a todos app, with a
gRPC server over PostgreSQL, was the reference until 0.35, when it moved to
a repository of its own):

- **Foundation on wasm/Android** is Isomer's (//foundation, over
swift-foundation; see "Foundation and CoreGraphics" below). Every
SwiftPM package an app links there depends on `@isomer//:foundation`
through `configure_package(target_deps = ...)` in its MODULE.bazel;
`tools/foundation/check_link.py <app targets>` finds one that doesn't.
- **Foundation on wasm/Android** is Isomer's, and the Swift SDK's (since
0.56): Isomer's Swift SDKs (AttilaTheFun/isomer_hermetic_toolchains,
docs/hermetic_toolchains.md) are swift.org's with corelibs Foundation out
and Isomer's family in, so every `import Foundation` there, a package's
included, is Isomer's with no dependency declared. A consumer registers
them by URL (`swift.android_sdk(url = …, sha256 = …)`,
`swift.wasm_sdk(…)`; README, "Isomer's Swift SDKs"): plain, or -i18n for
an app that formats (FoundationInternationalization and ICU). isomer's own
module registers the -i18n SDKs, the examples the plain ones.
- **Isomer's Swift is a Swift package (0.43; SwiftUI since 0.44)**: the
root Package.swift beside the Bazel module: Foundation, FoundationNetworking,
IsomerFoundation, CoreGraphics and Combine (0.43), and SwiftUI with what it
root Package.swift beside the Bazel module: CoreGraphics and Combine (0.43;
Linux's and Windows' alone since 0.56, when Foundation, FoundationNetworking
and IsomerFoundation went to the SDKs), and SwiftUI with what it
stands on (IsomerSwiftUI, CoreTransferable, UniformTypeIdentifiers, ImageIO,
PhotosUI, the SwiftUIMacros macro target; 0.44). rules_swift_package_manager
builds it as `@swiftpkg_isomer` in the root's one graph, under its own
Expand All @@ -161,8 +166,8 @@ a repository of its own):
`inject_repo(swift_deps, "isomer")`. isomer's own graph
(third_party/swift_packages, dev-only) and the examples' take the package by
path (cgrindel/rules_swift_package_manager#2638; with #2639 and #2640 the
registry's 1.25.0.isomer.1). Isomer's labels (`//foundation`,
`//core_graphics`, `//shared/isomer_swift_ui`, each platform's
registry's 1.25.0.isomer.1). Isomer's labels (`//core_graphics`,
`//shared/isomer_swift_ui`, each platform's
`libraries/swift_ui:core`, ...) are `one_configuration` wrappers over the
package's products. SwiftUI is one target, the same on every platform off
Apple: what differs is plugged in, each platform's host (IsomerWebHost,
Expand All @@ -171,9 +176,7 @@ a repository of its own):
which the host defines) and the GPU renderer (IsomerGPURenderer), Bazel
modules over it; `:swift_ui` is the group of SwiftUI and the host. What the
package can't express comes from the Bazel module through configure_package
`target_deps`: Foundation's internationalization (a marker module Foundation
checks with `canImport`, `--@isomer//foundation:internationalization`),
and the wire protos' Swift (shared/wire): the package generates it as it
`target_deps`: the wire protos' Swift (shared/wire): the package generates it as it
builds with swift-protobuf's build plugin (each target's
swift-protobuf-config.json), a plugin rules_swift_package_manager doesn't
run, so under Bazel swift_proto_library generates it as modules of their
Expand Down Expand Up @@ -211,7 +214,7 @@ a repository of its own):
toolchain by an absolute path that Bazel's inclusion check rejects; C
compiled for wasm had to avoid them (-nobuiltininc and shims, a
hand-declared pthread_self). rules_swift#1989 (a patch of isomer's from
0.34, merged upstream after 4.2.2; in the registry's rules_swift) gives
0.34, in upstream's 4.3.0) gives
compiles the Swift SDK's clang resource directory, as links already had:
the headers come from the SDK, among the action's inputs. A package's C
(swift_sql's amalgamation, through rules_swift_package_manager) then
Expand Down Expand Up @@ -549,10 +552,16 @@ SwiftUI libraries → swift_map/ → swift_gpu/ → metal/ → swift_ffi
registered through `--extra_toolchains`, the build-time Swift tools'
CppArchive fails in the sandbox (no apple-support-ar-wrapper);
`--strategy=CppArchive=local` works around it.
- **rules_swift 4.2.2.isomer.3** from the registry: upstream 4.2.2 and six
pull requests (MODULE.bazel). It sorts above the 4.2.2 rules_applecross
asks for, so MVS keeps it with no override in any root (until 0.40 the
fork was 4.1.0.isomer.N, held by an override every consumer repeated).
- **rules_swift 4.3.0.isomer.1** from the registry (since 0.56):
upstream 4.3.0 and four pull requests, each a patch from its head:
#1860 and #1990 (the wasip1-threads SDK beside the single-threaded one),
#1995 (Swift/C++ interop on Android) and #2000 (Android below API 28,
merged after 4.3.0). 4.3.0 has the rest of what 4.2.2.isomer.3 carried
(#1989, #1985), #2012 (`swift.android_sdk(url = …)`, Isomer's Swift
SDKs) and #1999 (no explicit modules for Android and wasm). It sorts
above the 4.2.2 rules_applecross asks for, so MVS keeps it with no
override in any root (until 0.40 the fork was 4.1.0.isomer.N, held by an
override every consumer repeated).
- **The Apple targets build on Linux too** (rules_applecross, 2026-10-26;
the project registry's 0.0.3.382f8c3, its main at 382f8c3, until it has a
release in the BCR): Xcode 27.0's SDKs from an SDK archive, the Swift
Expand Down Expand Up @@ -815,7 +824,7 @@ how Isomer runs it.
`_runtime(_multithreaded)`), and `SwiftFFILock` is a pthread mutex. A
host import called on a guest thread runs on the host's main thread
(posted when it answers nothing, waited for when it does). Foundation's
`Thread.isMainThread` there is foundation/wasi_thread_identity's: the
`Thread.isMainThread` there is CWasiThreadIdentity's (the SDK's): the
thread that ran the constructors. WasmKit's WASI Threads is
process-scoped: a threaded instance is kept for the life of the process
(no teardown, no hot reload), and a trap on a guest thread ends the app.
Expand Down Expand Up @@ -955,15 +964,15 @@ stubs (shared/swift_ui_core/NotYet.swift, generated: the compiler says "Not
yet in Isomer: <group>"); implementing one means running it again (or
deleting the stub); tools/parity/stubs_skip.txt keeps one out.

- **Foundation** (//foundation, `@isomer//:foundation`): built over
swift-foundation (swift-6.4.2-RELEASE's commit), a dependency of isomer's
Swift package (above; through rules_swift_package_manager since 0.40,
the registry's Bazel module 6.3.2.isomer.2 before), with patches
(MODULE.bazel says which and why). ICU is the Swift SDK's prebuilt one, a
patch to its manifest linking it by name, not swift-foundation-icu built
from source.
- **Foundation** (the Swift SDK's on Android and the web since 0.56; its
sources are isomer_hermetic_toolchains' `Isomer/Sources`, which were
//foundation's until then; docs/hermetic_toolchains.md): built over
swift-foundation (swift-6.4.2-RELEASE, Isomer's patches as commits on
that repository's `isomer-6.4.2` branch) into Isomer's Swift SDKs, plain
and -i18n, by its `sdk/build.sh`. ICU is the Swift SDK's prebuilt one, linked
by name, not swift-foundation-icu built from source.
FoundationEssentials, plus what corelibs has that apps reach for, written
in Swift here: CharacterSet, NSString's string API (searching, replacing,
in Swift: CharacterSet, NSString's string API (searching, replacing,
trimming, comparing, percent encoding; built in swift-foundation's
package, `package_name = "swift-foundation"`, to search with Essentials'
own helpers), `String(format:)`, NSRange, NSRegularExpression
Expand All @@ -984,21 +993,21 @@ deleting the stub); tools/parity/stubs_skip.txt keeps one out.
argument domain: `-key value` among the program's arguments, or, where a
host starts no program with arguments (Android), in ISO_ARGUMENTS
(`am start -e ISO_ARGUMENTS '-reviews.fixture YES'`: the generated
activity sets each ISO_ extra in the environment). `--@isomer//foundation:internationalization`
adds FoundationInternationalization over the Swift SDK's prebuilt ICU
activity sets each ISO_ extra in the environment). The -i18n SDKs' Foundation
re-exports FoundationInternationalization over the Swift SDK's prebuilt ICU
(lib_FoundationICU.a); `isomer_web_app(icu_locales = [...])` keeps only
those languages' ICU data (34 MB → 6-7 MB). Linux and Windows still use
the toolchain's corelibs Foundation; servers too.
- Every library that imports Foundation must depend on
`@isomer//:foundation` (SwiftPM packages through `configure_package(
target_deps = ...)`), or it finds the Swift SDK's Foundation, which
then links beside Isomer's (duplicate `Foundation` symbols).
`tools/foundation/check_link.py [<bazel flags>] <targets>` names the
leak; give it the flags the targets were built with (it refuses to pass
on autolink files that are not on disk).
those languages' ICU data (34 MB → 6-7 MB).
`--@isomer//foundation:internationalization` built that in when isomer
built Foundation; since 0.56 it checks that the SDK registered is the
-i18n one (foundation/internationalization). Isomer's modules in the SDKs
are built resilient (library evolution), as an Apple SDK's are. Linux and
Windows still use the toolchain's corelibs Foundation; servers too.
- `@isomer//:foundation` and `@isomer//:isomer_foundation` are empty
dependencies since 0.56 (a library needs neither: the SDK's modules are
found and autolinked), kept for the BUILD files that name them.
- **FoundationNetworking** (0.39.15): where Isomer's Foundation is the
Foundation (Android, the web), `@isomer//:foundation` brings a module
of that name too (//foundation/networking), which re-exports Isomer's
Foundation (Android, the web), the SDK has a module of that name too,
which re-exports Isomer's
Foundation, whose URLSession, URLRequest and URLResponse are those
corelibs keeps there. Code written for Linux (`#if
canImport(FoundationNetworking) import FoundationNetworking`) then sees
Expand All @@ -1010,10 +1019,10 @@ deleting the stub); tools/parity/stubs_skip.txt keeps one out.
rules_swift_package_manager keeps the LAST configure_package per
package and visits the root module first: a dependency's tag beats the
root's.
- The `:foundation` aliases are `one_configuration` wrappers
(foundation/defs.bzl): RSPM's per-package minimum-OS transitions would
otherwise build Foundation twice (every Apple platform's option is
cleared: a web site bundled into an iOS app builds under `ios`).
- Isomer's package modules are reached through `one_configuration`
wrappers (foundation/defs.bzl): RSPM's per-package minimum-OS
transitions would otherwise build them twice (every Apple platform's
option is cleared: a web site bundled into an iOS app builds under `ios`).
- A module renamed away (SwiftUIExtensions before 0.31) can survive as a
stale .swiftmodule in Bazel's output directory, beside the module that
replaced it, and shadow it: import the new name and depend on its target.
Expand Down Expand Up @@ -1093,8 +1102,8 @@ deleting the stub); tools/parity/stubs_skip.txt keeps one out.
interface has them, without delegates (foundation/URLSession.swift says
where each kind of URL goes). file: and data: URLs are read in Swift;
http(s) and ws(s) go through transports a host installs in
**IsomerFoundation** (//foundation/isomer_foundation,
`@isomer//:isomer_foundation`): `IsomerNetwork.http` (an
**IsomerFoundation** (a module of Isomer's Swift SDKs, the toolchains'
`Isomer/Sources/IsomerFoundation`): `IsomerNetwork.http` (an
`HTTPTransport`: one exchange, whole bodies, `NetworkTransportError`
for no response) and `IsomerNetwork.webSocket` (a
`WebSocketTransport` whose connections send text or data and receive
Expand Down
43 changes: 22 additions & 21 deletions BUILD.bazel
Original file line number Diff line number Diff line change
Expand Up @@ -44,38 +44,38 @@ alias(
visibility = ["//visibility:public"],
)

# Where `import Foundation` and `import CoreGraphics` come from: Apple's on
# Apple platforms (nothing to link), Isomer's on wasm and Android. A library that
# imports Foundation and is built for a non-Apple platform depends on
# `@isomer//:foundation`, which an application's other libraries (a SwiftPM
# package through rules_swift_package_manager's `target_deps`, a label flag)
# can be pointed at.
# Where `import Foundation` and `import CoreGraphics` come from: the Swift
# SDK's, so nothing to link. Apple's on Apple platforms; Isomer's on Android
# and the web, whose Swift SDKs (Isomer's, since 0.56: README, "Upgrading
# isomer") carry Isomer's Foundation; on Linux and Windows still the
# toolchain's corelibs Foundation (with Isomer's CoreGraphics beside it,
# :core_graphics). No library needs to depend on this any more: it stays, an
# empty dependency, for the BUILD files and `target_deps` that name it, and
# on Android and the web it carries the check that
# --@isomer//foundation:internationalization's SDK is the -i18n one
# (foundation/BUILD.bazel).
alias(
name = "foundation",
actual = select({
# A compiled feature (apple/compiled): Apple's Foundation with
# Isomer's Observation and Synchronization.
"//apple/compiled:feature_on": "//apple/libraries/compiled_swift_ui:foundation",
"@platforms//os:wasi": "//foundation:for_dependents",
"@platforms//os:android": "//foundation:for_dependents",
# Apple's frameworks; on Linux and Windows still the toolchain's
# Foundation (with Isomer's CoreGraphics beside it, :core_graphics).
"@platforms//os:wasi": "//foundation:from_sdk",
"@platforms//os:android": "//foundation:from_sdk",
"//conditions:default": ":system_framework",
}),
visibility = ["//visibility:public"],
)

# What a host installs beneath Isomer's Foundation (URLSession's transports,
# UserDefaults' store): IsomerFoundation, on the platforms with Isomer's
# Foundation; nothing on Apple platforms, where it has no place (code that
# builds for both guards with `#if canImport(IsomerFoundation)`).
# UserDefaults' store): IsomerFoundation, a module of Isomer's Swift SDKs on
# Android and the web (since 0.56), so nothing to link; nothing on other
# platforms, where it has no place (code that builds for both guards with
# `#if canImport(IsomerFoundation)`). An empty dependency, for the BUILD
# files that name it.
alias(
name = "isomer_foundation",
actual = select({
"@platforms//os:wasi": "//foundation/isomer_foundation:for_dependents",
"@platforms//os:android": "//foundation/isomer_foundation:for_dependents",
"//conditions:default": ":system_framework",
}),
actual = ":system_framework",
visibility = ["//visibility:public"],
)

Expand All @@ -99,9 +99,10 @@ alias(
alias(
name = "core_graphics",
actual = select({
"@platforms//os:wasi": "//core_graphics:for_dependents",
"@platforms//os:android": "//core_graphics:for_dependents",
# Beside the toolchain's Foundation there: what it lacks
# Apple's on Apple platforms, the Swift SDK's on Android and the web
# (Isomer's SDKs carry Isomer's CoreGraphics): nothing to link. On
# Linux and Windows Isomer's, built here, beside the toolchain's
# Foundation there: what it lacks
# (CGAffineTransform, CGPath, CGColor...; core_graphics/BUILD.bazel).
"@platforms//os:linux": "//core_graphics:for_dependents",
"@platforms//os:windows": "//core_graphics:for_dependents",
Expand Down
Loading
Loading