expo-modules-macros 0.20.0 → 0.22.0

package/.github/workflows/linux.yml

@@ -0,0 +1,132 @@
+name: Linux
+
+# Builds and tests the package on Linux, and checks the release tool and its package there.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch: {}
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    working-directory: apple
+    shell: bash
+
+jobs:
+  linux:
+    name: Build & test (Linux ${{ matrix.arch }})
+    runs-on: ${{ matrix.runner }}
+    # The release tool needs the glibc version that it's built against or a newer one. Red Hat UBI 9
+    # has glibc 2.34, the oldest version that the package supports. The Publish workflow builds the
+    # tool in the same image.
+    container: swift:6.4.0-rhel-ubi9@sha256:802a003f1eacbca9c20664a8ba79621d13f4538c3d329e745b7f8d53c70604a3
+    # The limit stops a hang, for example in the plugin server, from holding a runner for the default
+    # 6 hours.
+    timeout-minutes: 30
+    env:
+      # The newest glibc symbol version that the release tool may need. The READMEs of the Linux
+      # packages name it.
+      MAX_GLIBC_VERSION: '2.34'
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: x64
+            runner: ubuntu-24.04
+          - arch: arm64
+            runner: ubuntu-24.04-arm
+    steps:
+      - name: Checkout
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - name: Setup Node
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+
+      - name: Cache SwiftPM build
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: apple/.build
+          key: spm-${{ github.repository }}-${{ runner.os }}-${{ matrix.arch }}-${{ hashFiles('apple/Package.resolved') }}
+          restore-keys: |
+            spm-${{ github.repository }}-${{ runner.os }}-${{ matrix.arch }}-
+
+      - name: Build
+        run: swift build
+
+      - name: Test
+        run: swift test
+
+      - name: Build release tool
+        # Runs `npm run build` (scripts/build.js): builds the release plugin binary for this
+        # architecture as platforms/linux-<arch>/ExpoModulesMacros.
+        working-directory: ${{ github.workspace }}
+        run: npm run build
+
+      - name: Verify the release tool
+        # With no arguments it is the plugin server, which exits when stdin closes; with arguments it
+        # is the scanner CLI.
+        run: |
+          tool="../platforms/linux-${{ matrix.arch }}/ExpoModulesMacros"
+          # The Swift runtime must be linked in statically, so no Swift library may be a dependency.
+          needed="$(readelf --dynamic "$tool" | sed -n 's/.*(NEEDED).*\[\(.*\)\]$/\1/p')"
+          echo "Needed libraries:" $needed
+          if echo "$needed" | grep -E 'swift|Foundation|dispatch|BlocksRuntime'; then
+            echo "The release tool links a Swift library dynamically"
+            exit 1
+          fi
+          glibc="$(objdump -T "$tool" | grep -o 'GLIBC_[0-9][0-9.]*' | sed 's/^GLIBC_//' | sort -uV | tail -n 1)"
+          echo "Newest glibc symbol version: $glibc"
+          if [ "$(printf '%s\n' "$glibc" "$MAX_GLIBC_VERSION" | sort -V | tail -n 1)" != "$MAX_GLIBC_VERSION" ]; then
+            echo "The release tool needs glibc $glibc, newer than $MAX_GLIBC_VERSION"
+            exit 1
+          fi
+          "$tool" < /dev/null
+          "$tool" --help > /dev/null
+
+      - name: Pack the platform package
+        # Checks what `npm pack` would publish from `platforms/linux-<arch>`, where the release build
+        # put the tool: the executable with its executable bit, the README, the license and the
+        # manifest, with the `os`, `cpu` and `libc` fields for this machine.
+        working-directory: ${{ github.workspace }}
+        run: |
+          # The `./` matters: npm reads `platforms/linux-<arch>` as a GitHub repository.
+          npm pack "./platforms/linux-${{ matrix.arch }}" --pack-destination "$RUNNER_TEMP" --json > "$RUNNER_TEMP/pack.json"
+          node - "$RUNNER_TEMP/pack.json" "${{ matrix.arch }}" <<'EOF'
+          const fs = require('node:fs');
+          const [packPath, arch] = process.argv.slice(2);
+          const [pack] = JSON.parse(fs.readFileSync(packPath, 'utf8'));
+          const files = pack.files.map((file) => file.path).sort().join(',');
+          console.log(`${pack.filename}: ${files} (${pack.size} bytes packed)`);
+          if (files !== 'ExpoModulesMacros,LICENSE,README.md,package.json') {
+            throw new Error(`Unexpected files: ${files}`);
+          }
+          const tool = pack.files.find((file) => file.path === 'ExpoModulesMacros');
+          if ((tool.mode & 0o111) === 0) {
+            throw new Error(`ExpoModulesMacros is packed without the executable bit (mode ${tool.mode.toString(8)})`);
+          }
+          const manifest = JSON.parse(fs.readFileSync(`platforms/linux-${arch}/package.json`, 'utf8'));
+          const fields = [manifest.os, manifest.cpu, manifest.libc].join(' / ');
+          if (fields !== `linux / ${arch} / glibc`) {
+            throw new Error(`Unexpected os / cpu / libc: ${fields}`);
+          }
+          fs.appendFileSync(process.env.GITHUB_ENV, `PLATFORM_PACKAGE_TARBALL=${process.env.RUNNER_TEMP}/${pack.filename}\n`);
+          EOF
+
+      - name: Scan through the TypeScript wrapper
+        # Installs the packed platform package. The wrapper must find the executable in
+        # `@expo/modules-macros-linux-<arch>`, as it would in a project, not the local build.
+        working-directory: ${{ github.workspace }}
+        run: |
+          npm install
+          npm install --no-save "$PLATFORM_PACKAGE_TARBALL"
+          npm run build:ts
+          node scripts/check-scan.js .
+

package/.github/workflows/publish.yml

@@ -70,11 +70,147 @@ jobs:
           path: platforms/win32-${{ matrix.arch }}/ExpoModulesMacros.exe
           if-no-files-found: error
 
+  build-linux:
+    name: Build Linux tool (${{ matrix.arch }})
+    # SwiftPM builds macro tools only for the host, so each architecture builds on a runner of its own.
+    runs-on: ${{ matrix.runner }}
+    # The tool needs the glibc version that it's built against or a newer one. Red Hat UBI 9 has
+    # glibc 2.34, the oldest version that the package supports. The Linux workflow uses the same image.
+    container: swift:6.4.0-rhel-ubi9@sha256:802a003f1eacbca9c20664a8ba79621d13f4538c3d329e745b7f8d53c70604a3
+    timeout-minutes: 30
+    strategy:
+      matrix:
+        include:
+          - arch: x64
+            runner: ubuntu-24.04
+          - arch: arm64
+            runner: ubuntu-24.04-arm
+    steps:
+      - name: Checkout
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - name: Setup Node
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+
+      - name: Build release tool
+        # Runs scripts/build.js: builds the release plugin binary for this architecture as
+        # platforms/linux-<arch>/ExpoModulesMacros.
+        run: npm run build
+
+      - name: Upload tool
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          # Named after the package directory, like the Windows artifacts.
+          name: linux-${{ matrix.arch }}
+          path: platforms/linux-${{ matrix.arch }}/ExpoModulesMacros
+          if-no-files-found: error
+
+  verify-windows:
+    name: Verify Windows tool (${{ matrix.arch }})
+    needs: build-windows
+    # Installs the release tool from its packed package and scans through the TypeScript wrapper,
+    # before anything is published. The runner has no Swift toolchain.
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 15
+    strategy:
+      matrix:
+        include:
+          - arch: x64
+            runner: windows-latest
+          - arch: arm64
+            runner: windows-11-arm
+    steps:
+      - name: Checkout
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - name: Setup Node
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+
+      - name: Download tool
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: win32-${{ matrix.arch }}
+          path: platforms/win32-${{ matrix.arch }}
+
+      - name: Install the packed tool and scan
+        shell: pwsh
+        run: |
+          # The `./` matters: npm reads `platforms/win32-<arch>` as a GitHub repository.
+          $pack = npm pack "./platforms/win32-${{ matrix.arch }}" --pack-destination $env:RUNNER_TEMP --json | ConvertFrom-Json
+          if ($LASTEXITCODE -ne 0) { throw "npm pack failed" }
+          npm install
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          npm install --no-save (Join-Path $env:RUNNER_TEMP $pack[0].filename)
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          npm run build:ts
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          node scripts/check-scan.js .
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+  verify-linux:
+    name: Verify Linux tool (${{ matrix.arch }})
+    needs: build-linux
+    # Installs the release tool from its packed package, then scans through the TypeScript wrapper in
+    # images of the oldest distribution releases that the package supports, before anything is
+    # published. The images have no Swift toolchain, and the runner's Node runs in them.
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 15
+    defaults:
+      run:
+        shell: bash
+    strategy:
+      matrix:
+        include:
+          - arch: x64
+            runner: ubuntu-24.04
+          - arch: arm64
+            runner: ubuntu-24.04-arm
+    steps:
+      - name: Checkout
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - name: Setup Node
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+
+      - name: Download tool
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: linux-${{ matrix.arch }}
+          path: platforms/linux-${{ matrix.arch }}
+
+      - name: Install the packed tool
+        run: |
+          # Artifacts don't keep file modes, so the executable gets its executable bit back first.
+          chmod +x platforms/linux-${{ matrix.arch }}/ExpoModulesMacros
+          # The `./` matters: npm reads `platforms/linux-<arch>` as a GitHub repository.
+          npm pack "./platforms/linux-${{ matrix.arch }}" --pack-destination "$RUNNER_TEMP" --json > "$RUNNER_TEMP/pack.json"
+          tarball="$(node -p 'JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8"))[0].filename' "$RUNNER_TEMP/pack.json")"
+          npm install
+          npm install --no-save "$RUNNER_TEMP/$tarball"
+          npm run build:ts
+
+      - name: Scan on each distribution
+        run: |
+          node_dir="$(dirname "$(dirname "$(command -v node)")")"
+          for image in ubuntu:22.04 debian:12 amazonlinux:2023; do
+            echo "::group::$image"
+            run=(docker run --rm -v "$PWD:/work:ro" -v "$node_dir:/node:ro" -w /work "$image")
+            "${run[@]}" getconf GNU_LIBC_VERSION
+            "${run[@]}" /node/bin/node scripts/check-scan.js .
+            echo "::endgroup::"
+          done
+
   publish:
     name: Build and publish to npm
-    needs: build-windows
-    # Builds the native macOS tool binary, so it must run on macOS. The Windows binaries come from the
-    # build-windows jobs.
+    needs: [build-windows, build-linux, verify-windows, verify-linux]
+    # Builds the native macOS tool binary, so it must run on macOS. The Windows and Linux binaries come
+    # from the build-windows and build-linux jobs.
     # The package declares swift-tools-version 6.2, which requires Xcode 26+.
     runs-on: macos-26
     permissions:
@@ -151,25 +287,38 @@ jobs:
         # copies it to apple/ExpoModulesMacros, and strips it.
         run: npm run build
 
-      - name: Download Windows tools
-        # Each artifact goes into the directory of its name: `platforms/win32-<arch>`.
+      - name: Verify the macOS tool
+        # Scans through the TypeScript wrapper, which must find the binary in `apple/`, before
+        # anything is published. The verify-windows and verify-linux jobs check the other binaries.
+        run: |
+          npm run build:ts
+          node scripts/check-scan.js .
+
+      - name: Download Windows and Linux tools
+        # Each artifact goes into the directory of its name: `platforms/<platform>-<arch>`.
         uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
-          pattern: win32-*
+          pattern: '{win32,linux}-*'
           path: platforms
 
-      - name: Verify Windows tools
-        run: ls -l platforms/win32-x64/ExpoModulesMacros.exe platforms/win32-arm64/ExpoModulesMacros.exe
+      - name: Verify Windows and Linux tools
+        # Artifacts don't keep file modes, so the Linux executables get their executable bit back
+        # here. `npm publish` keeps it in the package.
+        run: |
+          chmod +x platforms/linux-x64/ExpoModulesMacros platforms/linux-arm64/ExpoModulesMacros
+          ls -l \
+            platforms/win32-x64/ExpoModulesMacros.exe platforms/win32-arm64/ExpoModulesMacros.exe \
+            platforms/linux-x64/ExpoModulesMacros platforms/linux-arm64/ExpoModulesMacros
 
-      - name: Publish the Windows packages
+      - name: Publish the Windows and Linux packages
         # Published before `expo-modules-macros`, whose optional dependencies point at them, so that
         # package is never on npm without them. Each package needs trusted publishing (OIDC)
         # configured on npmjs.com for this workflow.
         env:
           DRY_RUN: ${{ inputs.dry_run && '--dry-run' || '' }}
         run: |
-          for arch in x64 arm64; do
-            npm publish --access public --tag "${{ steps.bump.outputs.tag }}" $DRY_RUN "./platforms/win32-$arch"
+          for package in win32-x64 win32-arm64 linux-x64 linux-arm64; do
+            npm publish --access public --tag "${{ steps.bump.outputs.tag }}" $DRY_RUN "./platforms/$package"
           done
 
       - name: Publish

package/.github/workflows/swift-format.yml

@@ -0,0 +1,76 @@
+name: Swift Format
+
+# Checks that the Swift sources are formatted with the pinned swift-format version.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch: {}
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+env:
+  # Keep in sync with the version in the Development section of README.md.
+  SWIFT_FORMAT_VERSION: '604.0.0'
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-24.04
+    # The same image as the Linux workflow. swift-format links the Swift runtime from it.
+    container: swift:6.4.0-rhel-ubi9@sha256:802a003f1eacbca9c20664a8ba79621d13f4538c3d329e745b7f8d53c70604a3
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - name: Setup Node
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+
+      - name: Restore swift-format
+        id: swift-format-cache
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.local/bin/swift-format
+          # The binary links the Swift runtime of the container image, so the key changes with this
+          # file, which sets the image.
+          key: swift-format-${{ runner.os }}-${{ env.SWIFT_FORMAT_VERSION }}-${{ hashFiles('.github/workflows/swift-format.yml') }}
+
+      - name: Build swift-format
+        if: steps.swift-format-cache.outputs.cache-hit != 'true'
+        run: |
+          set -euo pipefail
+          src="$(mktemp -d)"
+          git clone --depth 1 --branch "$SWIFT_FORMAT_VERSION" https://github.com/swiftlang/swift-format.git "$src"
+          cd "$src"
+          swift build -c release --product swift-format
+          mkdir -p ~/.local/bin
+          cp "$(swift build -c release --show-bin-path)/swift-format" ~/.local/bin/swift-format
+
+      - name: Save swift-format
+        # Saves the binary before the lint, so that a run with findings doesn't build it again.
+        if: steps.swift-format-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.local/bin/swift-format
+          key: ${{ steps.swift-format-cache.outputs.cache-primary-key }}
+
+      - name: Add swift-format to PATH
+        run: echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Lint
+        run: |
+          # The script lists the files with `git ls-files`. The checkout belongs to another user than
+          # the container's root user, so Git needs it marked as safe.
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+          npm run swift:lint

package/.github/workflows/windows.yml

@@ -1,7 +1,6 @@
 name: Windows
 
-# Builds and tests the package on Windows, and checks the release tool there. The Windows binaries
-# aren't published yet, so this runs apart from the macOS workflow.
+# Builds and tests the package on Windows, and checks the release tool and its package there.
 
 on:
   push:
@@ -116,29 +115,5 @@ jobs:
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
           npm run build:ts
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
-          $fixture = Join-Path $env:RUNNER_TEMP "scan-fixture"
-          New-Item -ItemType Directory -Force $fixture | Out-Null
-          Set-Content (Join-Path $fixture "Module.swift") "@ExpoModule`npublic final class WindowsModule {}"
-          @'
-          const path = require('node:path');
-          const { getScannerBinaryPath, scanModules } = require(path.resolve('build'));
-          const binaryPath = getScannerBinaryPath();
-          const expected = path.join('node_modules', '@expo', `modules-macros-win32-${process.arch}`, 'ExpoModulesMacros.exe');
-          if (!binaryPath.endsWith(expected)) {
-            console.error(`getScannerBinaryPath() returned ${binaryPath}, not a path ending in ${expected}`);
-            process.exit(1);
-          }
-          console.log(`getScannerBinaryPath() returned ${binaryPath}`);
-          scanModules([process.argv[2]]).then((result) => {
-            const module = result.modules.find((candidate) => candidate.name === 'WindowsModule');
-            if (!module) {
-              console.error(JSON.stringify(result, null, 2));
-              process.exit(1);
-            }
-            console.log(`scanModules reported ${module.name} in ${module.file}`);
-          }, (error) => {
-            console.error(error);
-            process.exit(1);
-          });
-          '@ | Set-Content (Join-Path $env:RUNNER_TEMP "scan-check.js")
-          node (Join-Path $env:RUNNER_TEMP "scan-check.js") $fixture
+          node scripts/check-scan.js .
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

package/AGENTS.md

@@ -9,10 +9,11 @@
 - `apple/Sources/ExpoModulesScanner`: the scanner library. `Modules/` implements `scan-modules` (autolinking), `Exports/` implements `scan-exports` (type generation), `Core/` holds the shared parsing and `#if` evaluation, and `CLI.swift` is the command-line front end.
 - `apple/Sources/ExpoModulesOptimized`: declarations for the `@OptimizedFunction` macro.
 - `apple/Tests`: `ExpoModulesMacrosTests` (expansion tests) and `ExpoModulesScannerTests`.
-- `platforms/`: the Windows packages `@expo/modules-macros-win32-x64` and `-arm64` (a `package.json` with `os` and `cpu`, a README and a copy of `LICENSE`). The Publish workflow runs `scripts/set-platform-versions.js` to give them the version of this package. Their `ExpoModulesMacros.exe` is written there by `npm run build` on Windows and isn't committed.
+- `platforms/`: the Windows packages `@expo/modules-macros-win32-x64` and `-arm64`, and the Linux packages `@expo/modules-macros-linux-x64` and `-arm64` (a `package.json` with `os` and `cpu`, plus `libc` on Linux, a README and a copy of `LICENSE`). The Publish workflow runs `scripts/set-platform-versions.js` to give them the version of this package. Their `ExpoModulesMacros.exe` (Windows) or `ExpoModulesMacros` (Linux) is written there by `npm run build` on that platform and isn't committed.
 - `apple/PodTests`: a stub test so that `expo/expo` native tests can install this package as a pod. Do not add real tests here.
 - `src/`: the TypeScript wrapper around the scanner CLI. `types.ts` mirrors the Swift `Codable` output types by hand.
-- `scripts/build.js` (`npm run build`): builds the release binaries: the universal macOS `apple/ExpoModulesMacros` (committed and published), and on Windows `platforms/win32-<arch>/ExpoModulesMacros.exe` for the host architecture (not committed; published in that package).
+- `scripts/build.js` (`npm run build`): builds the release binaries: the universal macOS `apple/ExpoModulesMacros` (committed and published), and on Windows and Linux `platforms/win32-<arch>/ExpoModulesMacros.exe` or `platforms/linux-<arch>/ExpoModulesMacros` for the host architecture (not committed; published in that package).
+- `scripts/swift-format.js` (`npm run swift:format`, `npm run swift:lint`): runs swift-format on the `.swift` files that Git tracks or doesn't ignore, with the configuration in `.swift-format`.
 
 ## Commands
 
@@ -23,20 +24,29 @@ cd apple && swift build      # debug build
 cd apple && swift test       # all Swift tests
 npm run typecheck            # TypeScript wrapper
 npm run build                # release binary (slow; on macOS uses Rosetta for x86_64)
+npm run swift:format         # format the Swift sources in place
+npm run swift:lint           # check the formatting, as CI does
 ```
 
-CI runs on macOS (`.github/workflows/swift.yml`) and on Windows x64 and arm64 (`.github/workflows/windows.yml`). On macOS it runs the release build, checks both binary slices, then runs `swift test` and `npm run typecheck`. On Windows it builds and tests the package, builds the release binary, checks that it starts without the Swift runtime, packs it into its `platforms/` package (checking the files and the `os`/`cpu` fields), installs that package, and scans through the TypeScript wrapper, which must find the executable there. Code in `Sources` and `Tests` must not assume Apple platforms or POSIX paths.
+CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.github/workflows/windows.yml`), and on Linux x64 and arm64 (`.github/workflows/linux.yml`). On macOS it runs the release build, checks both binary slices, then runs `swift test` and `npm run typecheck`. On Windows it builds and tests the package, builds the release binary, checks that it starts without the Swift runtime, packs it into its `platforms/` package (checking the files and the `os`/`cpu` fields), installs that package, and scans through the TypeScript wrapper with `scripts/check-scan.js`, which must find the executable there. On Linux it does the same in the `swift:6.4.0-rhel-ubi9` image, and also checks that no Swift library is linked dynamically, the newest glibc symbol version that the binary needs, and that the package keeps the executable bit. The Swift Format workflow (`.github/workflows/swift-format.yml`) builds the pinned swift-format version and runs `npm run swift:lint`. Code in `Sources` and `Tests` must not assume Apple platforms or POSIX paths.
 
 ## Windows
 
 - Outside Apple platforms, `Sources` import `FoundationEssentials` instead of `Foundation` (`#if canImport(FoundationEssentials)`). Full Foundation brings in ICU, which would add tens of megabytes to the statically linked Windows binary. Don't use APIs that only `Foundation` has (`FileHandle`, `NSRegularExpression`, `CharacterSet`, `FileManager.enumerator`, `NSString` path methods); `Core/StandardStreams.swift` writes to stdout and stderr.
 - The Windows binaries link the Swift runtime statically (`-static-stdlib`), because Swift has no stable ABI on Windows and the scanner must also run without a Swift toolchain. SwiftPM's `--static-swift-stdlib` has no effect there.
 
+## Linux
+
+- The `FoundationEssentials` rule above applies on Linux too.
+- The Linux binaries link the Swift runtime statically (`-static-stdlib`; SwiftPM's `--static-swift-stdlib` doesn't apply to the macro tool here either) but link glibc and the GNU C++ runtime dynamically, so they need the glibc version they were built against or a newer one. CI and the Publish workflow build them in `swift:6.4.0-rhel-ubi9` (glibc 2.34), and the Linux workflow fails when the binary needs a newer glibc symbol than `MAX_GLIBC_VERSION`. A change to the build image must keep these and the glibc version in the READMEs in sync.
+
 ## Conventions
 
-- Swift uses 2-space indentation. Write new doc comments as `///` line comments, not `/** */` blocks.
+- swift-format formats the Swift sources. After you change Swift code, run `npm run swift:format` and then `npm run swift:lint`, which also reports the rules that the formatter doesn't fix. `.swift-format` is a copy of the configuration in `expo/expo`, so keep the two the same. Each repository pins its own swift-format version.
+- The scripts run the swift-format on `PATH`, or on macOS the one in Xcode when there is none. CI builds the version in `SWIFT_FORMAT_VERSION` (`.github/workflows/swift-format.yml`, also named in the README), which can format differently from the one in Xcode. When CI reports a finding that the local lint doesn't, fix it as CI reports it.
+- Write new doc comments as `///` line comments, not `/** */` blocks.
 - Tests use Swift Testing (`import Testing`, `@Test`) with backtick-quoted descriptive names, for example ``func `Prunes .build, Pods, .git, and node_modules directories`()``.
-- Macro tests compare full expansions with `assertMacroExpansion` from `SwiftSyntaxMacrosGenericTestSupport`, using `indentationWidth: .spaces(2)`. Each test file wraps it in a local `assertExpansion` helper.
+- Macro tests compare full expansions with `assertMacroExpansion` from `SwiftSyntaxMacrosGenericTestSupport`, using `indentationWidth: .spaces(2)`. Each test file wraps it in a local `assertExpansion` helper that passes `recordIssue` (`IssueRecording.swift`) as the failure handler.
 - Scanner tests reach internal API with `@testable import ExpoModulesScanner`. Do not make scanner types `public` only for tests.
 - `@JS` applies to functions, properties and initializers. Do not write code or comments that assume it marks only functions.
 - Code comments describe the code as it is. Do not refer to open PRs, branches or planned work.
@@ -44,7 +54,7 @@ CI runs on macOS (`.github/workflows/swift.yml`) and on Windows x64 and arm64 (`
 ## Changing macros
 
 - The scanner re-implements the macros' naming and member rules on the syntax tree; it does not call the macro code. When a macro changes which members it binds or how it names them (the `@JS` name override, the `on` prefix `@Event` strips, which properties `@Record` treats as fields), change `scan-exports` to match, or generated TypeScript types drift from the runtime.
-- The scanner only parses files that match the pre-filter built by `macroAttributeRegex` in `Core/SourceScan.swift`. A new attribute or conformance the scanner must detect has to be added there, or files that use it are skipped without an error.
+- The scanner only parses files that pass the pre-filter, `MacroPrefilter` in `Core/SourceScan.swift`. Each command builds it from the `macros` and `conformances` arguments of its `scanFiles` call. A new attribute or conformance the scanner must detect has to be added to those arguments (an attribute also needs a `DetectedMacro` case), or files that use it are skipped without an error.
 - A new macro needs: the implementation in `apple/Sources/ExpoModulesMacros`, an entry in `providingMacros` in `Plugin.swift`, an expansion test file, the `#externalMacro` declaration in `expo-modules-core`, and an entry in the macro list in `README.md`.
 
 ## Contracts with other packages
@@ -52,14 +62,14 @@ CI runs on macOS (`.github/workflows/swift.yml`) and on Windows x64 and arm64 (`
 - **Macro declarations live in `expo-modules-core`** (`ios/Core/ExpoModulesMacros.swift` in `expo/expo`), as `#externalMacro(module: "ExpoModulesMacros", type: ...)`. Adding a macro, renaming a macro type or changing a macro's signature needs a matching edit there, and the type must be listed in `providingMacros` in `Plugin.swift`.
 - **Generated code calls `expo-modules-core` API.** An expansion that uses a new core symbol only works with a core version that has it.
 - **Scanner output is versioned.** `scanModulesSchemaVersion` (`Modules/ScanModules.swift`) and `scanExportsSchemaVersion` (`Exports/ExportedSurface.swift`) change independently. When the output shape of a command changes, bump its version and update the matching `SUPPORTED_SCAN_*_SCHEMA_VERSION` constant and mirror types in `src/types.ts`. `expo-modules-autolinking` also checks the `scan-modules` version.
-- **The binary path is part of the contract.** `expo-modules-autolinking` resolves this package from `expo-modules-core` and passes `-load-plugin-executable <package>/apple/<binary>#ExpoModulesMacros` to the compiler. The scanner wrapper in autolinking uses the same path, and `expo-modules-cli` uses `getScannerBinaryPath()`. On Windows the binary is `ExpoModulesMacros.exe` in `@expo/modules-macros-win32-<arch>`. Renaming or moving a binary needs a matching change in `expo/expo`.
+- **The binary path is part of the contract.** `expo-modules-autolinking` resolves this package from `expo-modules-core` and passes `-load-plugin-executable <package>/apple/<binary>#ExpoModulesMacros` to the compiler. The scanner wrapper in autolinking uses the same path, and `expo-modules-cli` uses `getScannerBinaryPath()`. On Windows the binary is `ExpoModulesMacros.exe` in `@expo/modules-macros-win32-<arch>`, and on Linux `ExpoModulesMacros` in `@expo/modules-macros-linux-<arch>`. Renaming or moving a binary needs a matching change in `expo/expo`.
 
 ## Releases
 
-- Do not rebuild or commit the binary under `apple/` in a feature change. Only the **Publish** workflow (`.github/workflows/publish.yml`, manual) rebuilds it, and it commits the result as `Release vX.Y.Z` after the npm publish succeeds. It also builds the Windows binaries and publishes them in the `platforms/` packages, with the same version.
+- Do not rebuild or commit the binary under `apple/` in a feature change. Only the **Publish** workflow (`.github/workflows/publish.yml`, manual) rebuilds it, and it commits the result as `Release vX.Y.Z` after the npm publish succeeds. It also builds the Windows and Linux binaries and publishes them in the `platforms/` packages, with the same version. Before it publishes anything, it installs each binary from its packed package and scans through the TypeScript wrapper with `scripts/check-scan.js`.
 - Do not edit the `version` in `package.json` by hand. The Publish workflow bumps it.
 - Commit and PR titles are short and imperative, with code identifiers in backticks, for example ``Report `@Union` types in `scan-exports` ``.
 
 ## Installed copies
 
-In `node_modules`, the compiler runs the prebuilt binary `apple/ExpoModulesMacros` (on Windows, `ExpoModulesMacros.exe` from `@expo/modules-macros-win32-<arch>`); editing the Swift sources there has no effect. Macro and scanner fixes belong in this repository and ship in a new release. The TypeScript wrapper ships compiled in `build/`, since `src/` is not published.
+In `node_modules`, the compiler runs the prebuilt binary `apple/ExpoModulesMacros` (on Windows and Linux, the binary from `@expo/modules-macros-<platform>-<arch>`); editing the Swift sources there has no effect. Macro and scanner fixes belong in this repository and ship in a new release. The TypeScript wrapper ships compiled in `build/`, since `src/` is not published.

package/README.md

@@ -15,15 +15,20 @@ The same executable doubles as a source scanner CLI.
 
 This package is not meant to be installed directly. It is a dependency of `expo-modules-core`, so every Expo project already has it. The published package contains a prebuilt universal (arm64 + x86_64) macOS binary at `apple/ExpoModulesMacros`, so consumers never build the plugin themselves.
 
-The Windows binaries ship in their own packages, `@expo/modules-macros-win32-x64` and `@expo/modules-macros-win32-arm64`, each with an `ExpoModulesMacros.exe`. This package lists them as optional dependencies, and their `os` and `cpu` fields make npm, pnpm and Yarn install only the one that matches a Windows machine, so other machines don't download them. The Swift runtime is linked in statically, so the executables run without a Swift toolchain; they need only Windows system libraries and the Microsoft Visual C++ runtime.
+The Windows and Linux binaries ship in their own packages, one per platform and architecture:
+
+- `@expo/modules-macros-win32-x64` and `@expo/modules-macros-win32-arm64`, each with an `ExpoModulesMacros.exe`. They need only Windows system libraries and the Microsoft Visual C++ runtime.
+- `@expo/modules-macros-linux-x64` and `@expo/modules-macros-linux-arm64`, each with an `ExpoModulesMacros`. They need glibc 2.34 or newer and the GNU C++ runtime (`libstdc++` and `libgcc_s`), for example on Ubuntu 22.04, Debian 12, Red Hat Enterprise Linux 9 or Amazon Linux 2023. They don't run on musl distributions such as Alpine Linux.
+
+This package lists them as optional dependencies, and their `os`, `cpu` and (on Linux) `libc` fields make npm, pnpm and Yarn install only the one that matches the machine, so other machines don't download them. The Swift runtime is linked in statically, so the executables run without a Swift toolchain.
 
 # Macros
 
 - **`@ExpoModule(_ name: String? = nil, classes: [Any.Type] = [])`** on a class. Turns the class into a module: binds its `@JS` members into the module's JavaScript object and resolves the module name from the argument, falling back to the class name. It also synthesizes everything inheriting from `Module` used to provide, so a module class can carry any superclass, or none.
-- **`@JS(_ jsName: String? = nil, _ options: JSOptions...)`** on a member of a module or shared object. Marks a function, property or initializer for export. `@ExpoModule` and `@SharedObject` bind each marked member straight into the JavaScript object, with the argument decoding, the call and the result encoding inlined, so there is no dynamic per-call path. The JS name defaults to the Swift name; pass a string to override it. The macro also checks that every type crossing the boundary is convertible in the direction it travels, so a bad type is reported on the author's own declaration rather than on the enclosing type. The `.concurrent` option moves an `async` body off the JavaScript thread while still decoding and encoding on it. A function or initializer can take a closure argument, such as `(Point) throws -> Size` or `(String) async throws -> Data`. JavaScript passes a function for it, and native code can store the closure and call it from any thread. A closure that throws or returns a value blocks the caller until JavaScript returns, and an `async` closure suspends instead and awaits a promise that the function returns. A closure that returns a value must be `throws`, so that an error from JavaScript can reach the caller. A non-throwing `Void` closure returns before JavaScript reads its arguments, so don't change a class instance after passing it to one.
+- **`@JS(_ jsName: String? = nil, _ options: JSOptions...)`** on a member of a module or shared object. Marks a function, property or initializer for export. `@ExpoModule` and `@SharedObject` bind each marked member straight into the JavaScript object, with the argument decoding, the call and the result encoding inlined, so there is no dynamic per-call path. The JS name defaults to the Swift name; pass a string to override it. Two `@JS` members with the same JS name on one JavaScript object are a compile-time error, since JavaScript could reach only one of them. A shared object's static and instance members bind onto different objects, so they can share a name. The macro also checks that every type crossing the boundary is convertible in the direction it travels, so a bad type is reported on the author's own declaration rather than on the enclosing type. The `.concurrent` option moves an `async` body off the JavaScript thread while still decoding and encoding on it. The `.withAsync("name")` option binds a synchronous function a second time under that name, as a function that returns a promise and runs the body on the concurrent thread pool. That function isn't isolated to the JavaScript thread, so its body must be safe to run on any thread. The macro reports a function isolated to a global actor through its own attribute or its type's. When the isolation comes from elsewhere, such as a protocol or the module's default isolation, the error points into the generated code, so mark the function `nonisolated`. A function or initializer can take a closure argument, such as `(Point) throws -> Size` or `(String) async throws -> Data`. JavaScript passes a function for it, and native code can store the closure and call it from any thread. A closure that throws or returns a value blocks the caller until JavaScript returns, and an `async` closure suspends instead and awaits a promise that the function returns. A closure that returns a value must be `throws`, so that an error from JavaScript can reach the caller. A non-throwing `Void` closure returns before JavaScript reads its arguments, so don't change a class instance after passing it to one.
 - **`@Event(_ name: String? = nil, sync: Bool = false)`** on a function-typed `var`. Expands the property into a closure that emits the event, so calling the property sends it to JavaScript with the closure's parameter as the payload. The JS name defaults to the property name with a leading `on` stripped. `sync: true` dispatches inline instead of asynchronously.
 - **`@SharedObject(_ name: String? = nil)`** on a `SharedObject` subclass. Collects the class's `@JS` members into a class definition that a module exposes through `@ExpoModule(classes:)`.
-- **`@Record()`** on a record type. Treats every non-static, non-private, non-computed stored property as a field, with no per-field wrapper, and synthesizes the memberwise initializer, the conversions in both directions, and the `Record` conformance. Requiredness is inferred: a default value makes a field optional, an optional type makes it nullable and optional.
+- **`@Record()`** on a struct, or on a final class with no inheritance clause (declare a class's protocol conformances in an extension). Treats every non-static, non-private, non-computed stored property as a field, with no per-field wrapper, and synthesizes the memberwise initializer, the conversions in both directions, and the `Record` conformance. Requiredness is inferred: a default value makes a field optional, an optional type makes it nullable and optional.
 - **`@Union()`** on an enum whose cases each carry one associated value. Models a TypeScript union. Synthesizes the conversions in both directions, a typed accessor per payload type, and the `JavaScriptDecodable` and `JavaScriptEncodable` conformances. Decoding is ordered: the first case whose payload decodes wins, so the more specific case goes first.
 
 How that looks in a module:
@@ -97,13 +102,13 @@ The binary is a compiled executable, so each call still spawns a process. What t
 
 to `OTHER_SWIFT_FLAGS` for `ExpoModulesCore`, every pod that depends on it, and their test specs. Expo's SPM prebuilds pass the same flag when they generate `Package.swift`, so both build systems load the same binary.
 
-On Windows, the compiler loads `ExpoModulesMacros.exe` from `@expo/modules-macros-win32-<arch>` with the same flag. `getScannerBinaryPath()` in the TypeScript wrapper returns the binary for the current platform and architecture. On Windows it falls back to the local `npm run build` output in `platforms/win32-<arch>` when the platform package isn't installed, for example in this repository.
+On Windows and Linux, the compiler loads `ExpoModulesMacros.exe` from `@expo/modules-macros-win32-<arch>` or `ExpoModulesMacros` from `@expo/modules-macros-linux-<arch>` with the same flag. `getScannerBinaryPath()` in the TypeScript wrapper returns the binary for the current platform and architecture. On Windows and Linux it falls back to the local `npm run build` output in `platforms/<platform>-<arch>` when the platform package isn't installed, for example in this repository.
 
 The module and type names in `#externalMacro` must stay in sync with `apple/Sources/ExpoModulesMacros/Plugin.swift`.
 
 # Development
 
-Requires a toolchain with Swift 6.2 or newer: on macOS 13 or newer that means Xcode 26 or newer, and on Windows the Swift toolchain from swift.org (CI uses 6.4).
+Requires a toolchain with Swift 6.2 or newer: on macOS 13 or newer that means Xcode 26 or newer, and on Windows and Linux the Swift toolchain from swift.org (CI uses 6.4).
 
 ```sh
 cd apple
@@ -111,20 +116,34 @@ swift build
 swift test
 ```
 
+The Swift sources are formatted with [swift-format](https://github.com/swiftlang/swift-format), using the same configuration (`.swift-format`) as the `expo/expo` repository. `npm run swift:format` formats the `.swift` files that Git tracks or doesn't ignore in place, and `npm run swift:lint` checks them without changes, as CI does.
+
+The scripts run the `swift-format` on `PATH`, or on macOS the one in the selected Xcode when there is none on `PATH`. CI uses swift-format `604.0.0`, which can format differently from the one in Xcode. To get the version that CI uses, build it from source:
+
+```sh
+git clone --depth 1 --branch 604.0.0 https://github.com/swiftlang/swift-format.git /tmp/swift-format
+(cd /tmp/swift-format && swift build -c release --product swift-format)
+mkdir -p ~/.local/bin
+cp "$(cd /tmp/swift-format && swift build -c release --show-bin-path)/swift-format" ~/.local/bin/
+```
+
+Then add `~/.local/bin` to `PATH`.
+
 `npm run build` runs `scripts/build.js`, which builds the release binary with SwiftPM's native build system (Swift Build, the default since Swift 6.4, doesn't build a macro tool that no target in the package uses).
 
 - On macOS, it builds for arm64 and x86_64, merges the slices into `apple/ExpoModulesMacros` with `lipo`, strips it, and verifies both slices are present. SwiftPM only builds macro tools for the host architecture, so the x86_64 slice is produced by running the toolchain under Rosetta; the script installs Rosetta if it is missing.
 - On Windows, it builds for the host architecture only, with the Swift runtime linked in statically and without debug info, and writes `platforms/win32-<arch>/ExpoModulesMacros.exe` (`x64` or `arm64`, as Node's `process.arch` names them), the file that the package for that architecture publishes. It strips the executable with `llvm-strip` from the Swift toolchain and checks the architecture in its header.
+- On Linux, it also builds for the host architecture only, with the Swift runtime linked in statically, and writes `platforms/linux-<arch>/ExpoModulesMacros`. It strips the executable with `strip` and checks the architecture in its ELF header. The executable needs the glibc version of the machine it's built on or a newer one, so CI and the Publish workflow build it in the `swift:6.4.0-rhel-ubi9` image (Red Hat UBI 9, glibc 2.34).
 
-The macOS binary is committed to the repository. The Windows binaries aren't: the Publish workflow builds them and puts them into the packages in `platforms/`.
+The macOS binary is committed to the repository. The Windows and Linux binaries aren't: the Publish workflow builds them and puts them into the packages in `platforms/`.
 
 # Releasing
 
 The **Publish** workflow is manual (`workflow_dispatch`) and takes a release type. It bumps the version, builds the universal binary, and publishes to npm through OIDC trusted publishing. The commit, tag and GitHub release are created only after the publish succeeds, so a failed build leaves the branch untouched.
 
-Windows jobs (x64 and arm64) build the `.exe` files first. After the version bump, `scripts/set-platform-versions.js` gives the packages in `platforms/` the same version and lists them in this package's `optionalDependencies` with that exact version. The workflow publishes the two Windows packages before `expo-modules-macros`, so this package is never on npm without them. Each package needs trusted publishing configured on npmjs.com for the Publish workflow.
+Windows and Linux jobs (x64 and arm64 for each) build their binaries first. Verify jobs then install each binary from its packed package and scan through the TypeScript wrapper with `scripts/check-scan.js`, on Windows runners without Swift and, for Linux, in the Ubuntu 22.04, Debian 12 and Amazon Linux 2023 images. The publish job does the same for the macOS binary, so a failed check stops the release before anything is published. After the version bump, `scripts/set-platform-versions.js` gives the packages in `platforms/` the same version and lists them in this package's `optionalDependencies` with that exact version. The workflow publishes the four platform packages before `expo-modules-macros`, so this package is never on npm without them. Each package needs trusted publishing configured on npmjs.com for the Publish workflow.
 
-Prerelease versions (`prepatch`, `preminor`, `premajor`, `prerelease`) are published with the `next` dist-tag, and the others with `latest`. With **Dry run** checked, the workflow builds everything and runs `npm publish --dry-run` for the three packages, but doesn't publish, commit, tag or create a release. Use it to check a change to the workflow.
+Prerelease versions (`prepatch`, `preminor`, `premajor`, `prerelease`) are published with the `next` dist-tag, and the others with `latest`. With **Dry run** checked, the workflow builds everything and runs `npm publish --dry-run` for the five packages, but doesn't publish, commit, tag or create a release. Use it to check a change to the workflow.
 
 # Contributing