expo-modules-macros 0.19.1 → 0.21.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/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,10 @@
 - `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).
 
 ## Commands
 
@@ -25,13 +25,18 @@ npm run typecheck            # TypeScript wrapper
 npm run build                # release binary (slow; on macOS uses Rosetta for x86_64)
 ```
 
-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. 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.
@@ -52,14 +57,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,12 +15,17 @@ 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. 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.
@@ -81,11 +86,11 @@ Node consumers can call the scanner through this package instead of locating the
 ```ts
 import { scanModules, scanExports } from 'expo-modules-macros';
 
-const { modules, warnings } = await scanModules(['ios/'], { defines: ['DEBUG'] });
+const { modules, warnings } = await scanModules(['ios/'], { defines: ['DEBUG'], timeout: 30_000 });
 const { exports } = await scanExports(['ios/']);
 ```
 
-The binary is a compiled executable, so each call still spawns a process. What the wrapper owns is the part consumers would otherwise duplicate: resolving the shipped binary, building the arguments, parsing the JSON, checking `schemaVersion`, and turning a non-zero exit into a `ScannerError`. The result types are hand-written mirrors of the Swift `Codable` types, which is what the version check guards against drifting.
+The binary is a compiled executable, so each call still spawns a process. What the wrapper owns is the part consumers would otherwise duplicate: resolving the shipped binary, building the arguments, parsing the JSON, checking `schemaVersion`, and turning a non-zero exit or an exceeded `timeout` into a `ScannerError`. The result types are hand-written mirrors of the Swift `Codable` types, which is what the version check guards against drifting.
 
 # How the plugin reaches the compiler
 
@@ -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
@@ -115,16 +120,17 @@ swift test
 
 - 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
 

package/apple/Sources/ExpoModulesMacros/ClosureArguments.swift

@@ -344,7 +344,7 @@ internal func containsFunctionType(_ type: TypeSyntax) -> Bool {
 }
 
 /// The first function type in `type` or anywhere inside it, in source order.
-private func firstFunctionType(in type: some SyntaxProtocol) -> FunctionTypeSyntax? {
+internal func firstFunctionType(in type: some SyntaxProtocol) -> FunctionTypeSyntax? {
   if let functionType = type.as(FunctionTypeSyntax.self) {
     return functionType
   }

package/apple/Sources/ExpoModulesMacros/DecorateModuleBuilder.swift

@@ -23,10 +23,13 @@ internal struct JSFunction {
   let returnFreeForm: FreeFormConversion?
   let isThrowing: Bool
   let isAsync: Bool
+  /// The function's name in the source, where a JavaScript name collision is reported.
+  let nameToken: TokenSyntax
 
   init(funcDecl: FunctionDeclSyntax, attribute: AttributeSyntax) {
     self.swiftName = funcDecl.name.text
     self.jsName = jsNameArgument(of: attribute) ?? withoutBackticks(funcDecl.name.text)
+    self.nameToken = funcDecl.name
     self.parameters = Array(funcDecl.signature.parameterClause.parameters)
 
     let declaredReturnType = funcDecl.signature.returnClause?.type
@@ -206,8 +209,8 @@ internal struct JSFunction {
   }
 
   /// The flat (single-arity) call-and-encode lines used when no trailing parameter is omittable:
-  /// `let result = <callee>.f(...)` then the return encode (or the no-return `<callee>.f(...)` +
-  /// `.undefined()`).
+  /// `let result = <callee>.f(...)` then the return encode (or just `<callee>.f(...)` for a function
+  /// that returns nothing).
   private func callAndEncodeLines(receiver: Receiver, arity: Int, decodingFrom: Int) -> [String] {
     var lines: [String] = []
     for index in decodingFrom..<arity {
@@ -218,7 +221,6 @@ internal struct JSFunction {
       lines.append(contentsOf: encodeResultLines())
     } else {
       lines.append(callExpression(receiver: receiver, arity: arity))
-      lines.append("return .undefined()")
     }
     return lines
   }
@@ -229,7 +231,8 @@ internal struct JSFunction {
   /// `toJavaScriptValue(in:)` except for `Int`/`UInt`, where it range-checks
   /// and throws instead of silently encoding an out-of-safe-range value as a lossy number — the
   /// catchable error is the right behavior, and matches how non-primitive integers already encode. A
-  /// no-return function returns `.undefined()` instead.
+  /// no-return function has nothing to encode: its binding closure returns `Void` (see
+  /// `decorateStatements(object:receiver:)`).
   ///
   /// For an `async` function the encode must run on the JS thread. An `async` body may suspend and
   /// resume on an arbitrary cooperative-pool thread, and encoding a heap-allocated JS value (a string,
@@ -239,7 +242,7 @@ internal struct JSFunction {
   /// which always run on the JS thread — keep encoding directly without the wrapper.
   private func encodeResultLines() -> [String] {
     guard let returnType else {
-      return ["return .undefined()"]
+      return []
     }
     let encode = "try \(encodeCall(returnType, freeForm: returnFreeForm, of: "result"))"
     if isAsync {
@@ -272,11 +275,16 @@ internal struct JSFunction {
     // a shorthand `{ [capture] name, name in }` parameter; for a sync binding the explicit
     // `JavaScriptUnownedValue` also selects the (otherwise `@_disfavoredOverload`) unowned-`this`
     // overload.
+    // A sync function that returns nothing binds through the `Void` overload, which leaves JS's
+    // result as `undefined` without building and writing a value. The closure declares `-> Void`
+    // because a body of several statements without a `return` is otherwise ambiguous between the
+    // two unowned-`this` overloads.
     let captures = receiver.captureClause
     let parameters = "(this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer)"
+    let returnClause = returnType == nil && !isAsync ? " -> Void" : ""
 
     return """
-        \(object).setProperty("\(jsName)") { \(captures)\(parameters) in
+        \(object).setProperty("\(jsName)") { \(captures)\(parameters)\(returnClause) in
       \(bodyStatements(receiver: receiver, indent: "    "))
         }
       """
@@ -308,6 +316,8 @@ internal struct JSProperty {
   /// Whether the property is settable from JS: `true` for a stored `var` or a computed `var` with an
   /// explicit `set` accessor; `false` for a getter-only computed `var` or a `let`.
   let isSettable: Bool
+  /// The property's name in the source, where a JavaScript name collision is reported.
+  let nameToken: TokenSyntax
 
   /// The statements that install this property's accessor on the JS object, indented for the
   /// decorator body. Builds a descriptor object (`enumerable` + `get`, and `set` when settable) via
@@ -348,7 +358,7 @@ internal struct JSProperty {
       let setDecode = "\(callee).\(swiftName) = try \(decode)"
       lines.append(
         accessorClosure(
-          descriptorName, "set", receiver: receiver, body: "\(unwrap)\(setDecode)\nreturn .undefined()"))
+          descriptorName, "set", receiver: receiver, returnsVoid: true, body: "\(unwrap)\(setDecode)"))
     }
 
     lines.append("\(object).defineProperty(\"\(jsName)\", descriptor: \(descriptorName))")
@@ -361,8 +371,10 @@ internal struct JSProperty {
 
   /// One `descriptor.setProperty("get"/"set") { … }` accessor entry. The capture list follows the
   /// receiver: a module captures `self` strong; a shared object captures nothing of the instance.
+  /// A setter passes `returnsVoid`, so its closure declares `-> Void` and binds through the `Void`
+  /// overload, like a function that returns nothing.
   private func accessorClosure(
-    _ descriptorName: String, _ key: String, receiver: Receiver, body: String
+    _ descriptorName: String, _ key: String, receiver: Receiver, returnsVoid: Bool = false, body: String
   ) -> String {
     let captures = receiver.captureClause
     // Indent each line of a (possibly multi-line) body to sit one level inside the closure; a bare
@@ -377,8 +389,9 @@ internal struct JSProperty {
     // `borrowing JavaScriptUnownedValue` selects the unowned-`this` overload. A module ignores `this`;
     // a shared object unwraps it in the body.
     let parameters = "(this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer)"
+    let returnClause = returnsVoid ? " -> Void" : ""
     return """
-      \(descriptorName).setProperty("\(key)") { \(captures)\(parameters) in
+      \(descriptorName).setProperty("\(key)") { \(captures)\(parameters)\(returnClause) in
       \(indentedBody)
       }
       """
@@ -445,7 +458,7 @@ internal func buildDecorateSharedObjectPhase(
 }
 
 /// True when a return clause is absent or written as `Void` / `()` — i.e. the function returns
-/// nothing JS-visible, so the binding returns `.undefined()`.
+/// nothing JS-visible, so the binding closure returns `Void`.
 private func isVoidType(_ type: TypeSyntax?) -> Bool {
   guard let type else {
     return true