跳到主内容

TablePro 源码编译踩坑实录:6 千星的原生数据库客户端,关卡全在仓库外

TablePro 的编译卡点全在仓库外面:git clone 下来找不到 .xcodeproj,它被当成构建产物排除在 git 之外;工程文件要靠 XcodeGen 现场生成,生成前还得先下一个 158 MB 的预编译库包。三道关缺一道,编译就停在第一步。

这项目 6,351 星、Swift 原生、AGPL-3.0,主打"没有 Electron、没有 JDBC、没有 JS 运行时"。我本想编一个看代码结构,ls 完发现 apple/、linux/、scripts/ 都在,就是没有 .xcodeproj。先说结论:Windows 上编译不了,README 的 Platforms 表里 Windows 是 "No"。站内 别再只看 Star 选了 讲选型,这篇是源码层排查记录。

典型症状:三个报错,同一个病根

一,clone 完没有工程文件。根目录只有 apple/、linux/、scripts/、AGENTS.md、appcast.xml,搜 *.xcodeproj 一个都没有。

二,generate-project.sh 报缺 dylib。脚本注释写得很直白:macOS 的 project.yml 按路径点名了 Libs/dylibs/libssl.3.dylib 和 libcrypto.3.dylib,XcodeGen 在生成阶段就校验路径,缺了直接失败,并提示先跑 scripts/download-libs.sh。

三,iOS 工程报 "Target TablePro has a missing source directory"。这条也写在脚本注释里,是他们踩过的坑:iOS 流水线不该构建 macOS 工程,但两个一起生成就会因没下载 libs 全线失败。

排查路径:从外到内分四层

第一层,平台。README 表格把话说死:macOS 13+ 稳定、iOS/iPadOS 18+ 稳定、Linux(GNOME 50+)开发中未发布、Windows 是 No。

第二层,工具链。README 要 Xcode 26 或更晚加 XcodeGen。generate-project.sh 把要求钉成 REQUIRED_XCODEGEN_VERSION="2.46.0"——版本不一致不报错,只警告"结果可能与 CI 不同"然后继续,这种只警告不中断最埋雷。

第三层,工程生成。TablePro.xcodeproj 由 project.yml 生成,注释原话:"Both projects are build artifacts and are not in git",改过 project.yml 或增删源文件后都要重跑。

第四层,预编译依赖。download-libs.sh 从 Libs/release 读标签(形如 libs-6),用 gh release download 或 curl 拉包,再用仓库里 commit 的 checksums.sha256 校验。注释解释:"these libraries are force_loaded into a signed and notarized app"。libs-6 发布于 2026-10-31,macOS 包 158,369,088 字节。

根因定位:两个刻意为之的取舍

把工程文件当产物管。project.yml 是唯一事实来源,.xcodeproj 每次生成。好处是多人协作不会出现工程文件合并冲突(那玩意儿出了名难合),代价是每个新人第一步都要多跑一个脚本。

把 C 依赖预编译后当二进制资产发布。apple/scripts/ 下二十来个 build-*.sh:build-libpq.sh 7,709 字节、build-freetds.sh 12,861 字节、build-duckdb.sh 10,492 字节,SQLite、MariaDB、Cassandra 各一份。这些给维护者用,普通构建者只下成品——让每个人本地编二十个 C 库,构建时间会从十分钟变半天。

Linux 版也救不了 Windows 用户。linux/README.md 原话:"The Linux app shares no source with macOS." 那边是 Rust 写 GTK4,rust-toolchain.toml 钉 1.98,构建用 Meson 驱动 Cargo。这不是能顺手移植的代码库。

修复动作:macOS 上五步跑通

brew install xcodegen        # 版本尽量贴 2.46.0
cd apple                     # 后面命令都在这里跑
scripts/download-libs.sh     # 拉 158 MB 预编译库并校验
scripts/generate-project.sh  # 生成 TablePro.xcodeproj
xcodebuild -project TablePro.xcodeproj -scheme TablePro \
  -configuration Debug -skipPackagePluginValidation \
  CODE_SIGNING_ALLOWED=NO build

每步都有完成标志:第 3 步看 Libs/dylibs/ 下是否出现 libssl.3.dylib 和 libcrypto.3.dylib;第 4 步看根目录是否出现 TablePro.xcodeproj;第 5 步看日志末行 ** BUILD SUCCEEDED **,产物在 ~/Library/Developer/Xcode/DerivedData/TablePro-*/Build/Products/Debug/TablePro.app。

要装到机器上用再补一步:在 Configs/Secrets.xcconfig 填团队和 bundle id,去掉 CODE_SIGNING_ALLOWED=NO 重构建。这文件被 .gitignore 挡住,就是防别人的签名信息提交进来。

怎么防止再犯:两条边界先划清

平台边界。"No" 就是 No,别拿 Linux 版存在推断 Windows 也能编。Linux 版一个 linux-v* 标签都没有,原话 "Nothing is released yet",只能用 PPA(Ubuntu 26.04 / 26.10)或 COPR(Fedora 44+)装。它还有个坑:直接跑 ./_build/crates/app/tablepro 会 abort,报 GSettings schema app.tablepro.TablePro is not installed,得用 meson devenv -C _build 包一层。

许可证与版本边界。AGPL-3.0,自己用没问题,拿它做 SaaS 给客户用,网络分发条款会咬人,站内 电商源码二次开发的改造边界 讨论过同类问题。节奏也快:v0.83.0(2026-10-26)到 v0.83.1(2026-11-01)六天一个 patch,主包 dmg 75,105,991 字节,外加 30 个驱动 zip。要钉版本就钉 tag 别跟分支。站内 开源低代码平台搭建踩坑实录 栽的是同一个坑:源码路线第一道坎不是代码,是版本。

常见问题

问:我就想用不想编,Windows 有办法吗?
没有。作者明确写 Windows 不支持,也没有计划中的分支,要么换 Mac,要么另找跨平台方案。

问:能不能只生成 iOS 工程,跳过 macOS 那套依赖?
可以。generate-project.sh 支持 both|macos|ios 参数,传 ios 只生成移动端工程,不用先下 macOS 的 dylib。

问:源码在哪看?
github.com/TableProApp/TablePro:macOS/iOS 在 apple/,Linux 在 linux/,脚本在 apple/scripts/,架构决策记录在 linux/docs/decisions/。读 ADR 比读代码快。

相关阅读

分享到:

本文链接:https://www.biyeyuanma.cn/post/394.html

服务热线

加我微信

加我微信