[1002] 新增 macOS 预编译二进制包的 XPack Build 任务

.github/workflows/package.yml

@@ -248,3 +248,109 @@ jobs:
         prerelease: true
         files: |
           tmp/build/xpack/goldfish/*.zip
+
+  package-macos:
+    # GitHub 已退役 Intel macOS runner（macos-13 于 2025-12 下线），
+    # 当前所有 macOS runner 均为 Apple Silicon (arm64)，故只产出 arm64 包。
+    # Intel Mac 用户走源码编译（Homebrew formula 回退到 build）。
+    runs-on: macos-14
+    env:
+      XMAKE_GLOBALDIR: ${{ github.workspace }}/.xmake-global
+
+    steps:
+    - name: Setup xmake
+      uses: xmake-io/github-action-setup-xmake@v1
+      with:
+        xmake-version: v3.0.8
+
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 1
+
+    - name: Determine Version
+      run: |
+        REF_NAME="${{ github.ref }}"
+        MANUAL_VER="${{ inputs.manual_version }}"
+        if [ -n "$MANUAL_VER" ]; then
+          RAW_VERSION="$MANUAL_VER"
+        elif [[ "$REF_NAME" == refs/tags/* ]]; then
+          RAW_VERSION=${REF_NAME#refs/tags/}
+          RAW_VERSION=${RAW_VERSION//\//}
+        else
+          RAW_VERSION=$(date +%Y.%m.%d)
+        fi
+        if [[ "$RAW_VERSION" == v* ]]; then
+          CLEAN_VERSION=${RAW_VERSION#v}
+        else
+          CLEAN_VERSION="$RAW_VERSION"
+        fi
+        echo "VERSION_TAG=$RAW_VERSION" >> $GITHUB_ENV
+        echo "VERSION_NUM=$CLEAN_VERSION" >> $GITHUB_ENV
+        echo "Version tag: $RAW_VERSION"
+        echo "Version num: $CLEAN_VERSION"
+
+    - name: cache packages from xrepo
+      uses: actions/cache@v4
+      with:
+        path: ${{ env.XMAKE_GLOBALDIR }}/.xmake/packages
+        key: macos-14-xrepo-${{ hashFiles('**/xmake.lua') }}
+
+    - name: xmake repo --update
+      run: xmake repo --update
+
+    - name: Config and Build
+      run: |
+        xmake config -vyD -o tmp/build -m release --repl=true --yes
+        xmake build goldfish
+
+    - name: Build function doc index
+      run: ./bin/gf doc --build-json
+
+    - name: Package
+      run: xmake pack -vyD goldfish
+
+    - name: Verify package arch
+      run: |
+        # xmake xpack 用宿主机 arch；强制校验产物文件名里带 arm64，
+        # 防止 runner 实际架构与预期不符时悄悄产出错误命名的包。
+        DIR="tmp/build/xpack/goldfish"
+        echo "Expected arch: arm64"
+        ls -lh "$DIR"/*.tar.gz
+        if ! ls "$DIR"/*-arm64-*.tar.gz >/dev/null 2>&1; then
+          echo "::error::产物文件名里没找到 arm64，检查 xmake 是否正确识别了架构"
+          exit 1
+        fi
+
+    - name: Create summary table
+      run: |
+        DIR="tmp/build/xpack/goldfish"
+        echo "## macOS arm64 package" >> $GITHUB_STEP_SUMMARY
+        echo "" >> $GITHUB_STEP_SUMMARY
+        echo "| 文件名 | 大小 |" >> $GITHUB_STEP_SUMMARY
+        echo "|--------|------|" >> $GITHUB_STEP_SUMMARY
+        for pkg in "$DIR"/*.tar.gz; do
+            if [ -f "$pkg" ]; then
+                size=$(ls -lh "$pkg" | awk '{print $5}')
+                echo "| \`$(basename "$pkg")\` | $size |" >> $GITHUB_STEP_SUMMARY
+            fi
+        done
+        echo "" >> $GITHUB_STEP_SUMMARY
+        echo "*目录: \`$DIR\`*" >> $GITHUB_STEP_SUMMARY
+
+    - name: Upload macOS package artifact
+      uses: actions/upload-artifact@v4
+      if: github.event_name == 'workflow_dispatch'
+      with:
+        name: goldfish-macos-arm64-package
+        path: tmp/build/xpack/goldfish/*.tar.gz
+        retention-days: 30
+        if-no-files-found: error
+
+    - name: Release
+      uses: softprops/action-gh-release@v1
+      if: startsWith(github.ref, 'refs/tags/')
+      with:
+        prerelease: true
+        files: |
+          tmp/build/xpack/goldfish/*.tar.gz

devel/1002.md

@@ -0,0 +1,67 @@
+# [1002] 新增 macOS 预编译二进制包的 XPack Build 任务
+
+任务编号使用 0000 到 9999 的四位数字格式。
+
+## 1. 相关文档
+- [dddd.md](dddd.md) - 任务文档模板
+- [1001.md](1001.md) - 修复 Linux CI 因缺失 ninja 导致的构建失败
+
+## 2. 任务相关的代码文件
+- `xmake.lua`
+- `.github/workflows/package.yml`
+
+## 3. 如何测试
+
+### 3.1 确定性测试（单元测试）
+```bash
+# 本地验证 macOS 上能正确产出 targz 包，且文件名带 -darwin 后缀
+xmake f -c -vD -o tmp/build -m release --repl=true --yes
+xmake b goldfish
+xmake pack -vyD goldfish
+ls tmp/build/xpack/goldfish/
+# 期望产物形如：goldfish-scheme-arm64-v18.11.9-darwin.tar.gz
+```
+
+### 3.2 非确定性测试（文档验证）
+```bash
+# 检查 tar 包内部结构是否包含可执行文件与 stdlib
+tar tzf tmp/build/xpack/goldfish/*.tar.gz | head
+# 期望含 bin/gf 以及 share/goldfish/ 下的 .scm 文件
+```
+
+## 4. 如何提交
+
+提交前执行以下最少步骤：
+
+```bash
+bin/gf test --changed-since=main
+```
+
+## 5. 2026-06-15 新增 macOS 预编译二进制包的 XPack Build 任务
+
+### 5.1 What
+在 XPack Build 工作流中新增 `package-macos` job，为 macOS (arm64) 产出预编译的 `.tar.gz` 包并发布到 release。
+
+1. 在 `xmake.lua` 的 xpack 配置中为 macosx 平台设置 `set_formats("targz")`。
+2. 在 `xmake.lua` 的 xpack `on_load` 中为 macosx 平台设置带 `-darwin` 后缀的 basename：`goldfish-scheme-$(arch)-v$(version)-darwin`。
+3. 在 `package.yml` 中新增 `package-macos` job，在 `macos-14`(arm64) 上构建、打包并发布。
+
+### 5.2 Why
+此前的 `package.yml` 只产出 Debian (`.deb`) 与 Windows (`.zip`) 两类预编译包，没有 macOS 的二进制产物。第三方 Homebrew tap 只能从源码 tarball 编译安装（formula 里需要声明 `xmake`/`cmake`/`ninja` 作为构建依赖），用户每次 `brew install` 都要本地编译。
+
+上游提供 macOS 预编译二进制后，下游的 Homebrew formula 即可改为下载二进制安装，去掉编译依赖，显著缩短安装时间。这与现有的 Debian/Windows 打包流程对齐，补齐了三大桌面平台的发行物。
+
+### 5.3 How
+复用 `ci-macos.yml` 中已验证可用的 xmake config/build 步骤（`-m release --repl=true`），构建后调用 `xmake pack` 产出 tar.gz。
+
+- **格式选择**：macOS 上用 `targz` 而非 `zip`，因为 Homebrew 原生支持 tar.gz 解压；格式名是 `targz` 而非直觉上的 `tgz`（依据 `xmake pack --help` 列出的合法值：nsis/wix/deb/srpm/rpm/runself/targz/zip/srctargz/srczip）。
+- **命名约定**：basename 加 `-darwin` 后缀以与 Linux 包（`goldfish-scheme-$(arch)-v$(version)`）区分，便于 Homebrew formula 按平台精准匹配下载地址。
+- **架构覆盖（仅 arm64）**：最初设计为 `matrix` 同时跑 `macos-14`(arm64) 与 `macos-13`(x86_64)。但 GitHub 已于 2025-12-04 退役 `macos-13`（Intel）runner 镜像，当前所有 GitHub-hosted macOS runner 均为 Apple Silicon (arm64)，已无任何原生 Intel macOS runner 可用。因此改为只产出 arm64 包；Intel Mac 用户由 Homebrew formula 回退到源码编译（`brew install` 时从源码 build）。job 里保留 `Verify package arch` 步骤断言产物文件名含 `arm64`，防止 runner 实际架构不符时产出错误命名的包。
+- **runner 版本**：暂用 `macos-14`。需注意 `macos-14` 将于 2026-07-06 开始弃用、2026-11-02 彻底下线；届时需迁移到更新的标签（如 `macos-15`）。
+- **发布策略**：与现有 deb/zip job 保持一致，`workflow_dispatch` 时上传 artifact，打 tag 时以 `prerelease: true` 发到 GitHub Release。
+
+已在本机 (macOS arm64, xmake v3.0.6) 实测：`xmake pack` 成功产出 `goldfish-scheme-arm64-v18.11.9-darwin.tar.gz`，内部结构含 `bin/gf` 与 `share/goldfish/`。
+
+## 6. 之前的提交和任务描述
+
+无。

xmake.lua

@@ -201,6 +201,8 @@ includes("@builtin/xpack")
 xpack ("goldfish")
     if is_plat("windows") then
         set_formats("zip")
+    elseif is_plat("macosx") then
+        set_formats("targz")
     else
         set_formats("deb", "rpm", "srpm")
     end
@@ -224,6 +226,8 @@ xpack ("goldfish")
             package:set("basename", "goldfish-scheme-src-v$(version)")
         elseif is_plat("windows") then
             package:set("basename", "goldfish-scheme-$(arch)-v$(version)-win")
+        elseif is_plat("macosx") then
+            package:set("basename", "goldfish-scheme-$(arch)-v$(version)-darwin")
         else
             package:set("basename", "goldfish-scheme-$(arch)-v$(version)")
         end