docs: macOS ships the DMG alone, the pkg is retired

The .pkg existed to hand a fresh machine a copy that was not quarantined, so it
opened with no prompt at all. The DMG has now been verified to work on a fresh
machine - drag to /Applications, one approval on first launch - which is the same
one approval the DMG has always needed. So the second container bought nothing
and is dropped: one artifact per platform is less to keep straight, and nothing in
the channel changes.

What the docs say instead of recommending the package: install the DMG, allow the
first launch once. In-app updates still never prompt, because Shift's own
downloader sets no quarantine flag. The macos manifest key stays a DMG for the
reason it always did - the in-app handoff mounts it with hdiutil.

scripts/macos-pkg.sh stays in the tree and RELEASE.md says plainly that it is no
longer part of a release, so the next reader does not wonder whether a publish is
missing it. The 0.1.3 branch still holds the retired package because removing it
means re-publishing; it has no manifest key, so nothing can be served it.

The packaged note is rewritten for the same reason: it told a reader to download a
file that will no longer be built, and its verification section checked the
package instead of the image.
main
mula.liu 2026-10-26 10:47:48 +08:00
parent f2a1ff6d52
commit 58949bebd2
5 changed files with 58 additions and 83 deletions

View File

@ -292,7 +292,7 @@ Each is overridable in Settings. File actions offer a *collect everything in one
## Updates
A new macOS machine should install **`Shift-macOS-universal.pkg`**: builds are ad-hoc signed and not notarized, so Gatekeeper calls Shift an unidentified developer, and an installed package leaves the app free of the quarantine flag - it opens with no prompt. From the disk image, the first launch needs one approval (right-click → Open, or 允许 in System Settings → Privacy & Security). Details in `docs/RELEASE.md`.
A new macOS machine installs **`Shift-macOS-universal.dmg`**: builds are ad-hoc signed and not notarized, so Gatekeeper calls Shift an unidentified developer. Double-click the image, drag `Shift.app` to /Applications, then allow the first launch once (right-click → Open, or 允许 in System Settings → Privacy & Security). In-app updates download the same image without a browser, so they never prompt. Details in `docs/RELEASE.md`.
The update channel is this repository: a `releases` branch holding the installers plus `shift-update.json`, which names each artifact, its size and its SHA256. The feed URL is derived from the git remote at build time - Gitea, GitHub and GitLab forms are known, and `SHIFT_UPDATE_URL` overrides it - so no update service has to be deployed anywhere.

View File

@ -294,7 +294,7 @@ Shift 会持续维护局域网内其他 Shift 实例的列表,并据此提供
## 软件更新
新的 macOS 机器请安装 **`Shift-macOS-universal.pkg`**:本项目的构建采用 ad-hoc 签名且未做公证,Gatekeeper 会把 Shift 判为身份不明的开发者,而通过安装包安装不会把隔离属性带给应用,装好后打开不会再有提示。若改用磁盘镜像安装,首次打开需要允许一次(右键 → 打开,或在「系统设置 → 隐私与安全性」中点「允许」)。详见 `docs/RELEASE.md`。
新的 macOS 机器请安装 **`Shift-macOS-universal.dmg`**:本项目的构建采用 ad-hoc 签名且未做公证,Gatekeeper 会把 Shift 判为身份不明的开发者。双击挂载镜像,把 `Shift.app` 拖进「应用程序」,然后允许首次启动一次(右键 → 打开,或在「系统设置 → 隐私与安全性」中点「允许」)。软件内升级自己下载的是同一个镜像、不经浏览器,因此不会弹窗。详见 `docs/RELEASE.md`。
更新通道就是这个仓库:一条 `releases` 分支保存安装包以及 `shift-update.json` 清单,清单写明每个安装包的名称、体积与 SHA256。更新源地址在构建时由 git 远端推导——已适配 Gitea、GitHub、GitLab 三种形式,也可用 `SHIFT_UPDATE_URL` 覆盖——因此无需额外部署任何更新服务。

View File

@ -1,47 +1,32 @@
Shift 0.1.3 - macOS 通用(universal)
本文件说明 macOS 安装包是怎么打出来的、两个安装包各自负责什么、在其它机器上
会遇到什么,以及如何自己校验。完整细节见仓库 docs/RELEASE.md 的「macOS packaging」。
本文件说明 macOS 安装包是怎么打出来的、在其它机器上会遇到什么,以及如何自己校验。
完整细节见仓库 docs/RELEASE.md 的「macOS packaging」。
为什么有两个安装包
------------------
关于这个安装包
--------------
Shift 的 macOS 产物只有一个:Shift-macOS-universal.dmg,通用二进制,Apple silicon 与
Intel 都能用。它既是新机器的首次安装方式,也是软件内升级的载体(更新清单里的 macos
键指向它)。清单的键必须是 .dmg,因为软件内升级的交接脚本要用 hdiutil 挂载镜像再
取出应用包;早期曾随包发布的 .pkg 在验证过 DMG 可用后就撤掉了,不为它多维护一份
产物。
本项目的构建是 ad-hoc 签名(src-tauri/tauri.conf.json 里 signingIdentity 固定为
"-"),且没有 Apple Developer ID 可做公证。Gatekeeper 因此无法为任何 Shift 构建背书,
一台新机器上的表现取决于安装包的形式:
| 安装包 | 用途 | 新机器上的表现 |
| --- | --- | --- |
| Shift-macOS-universal.pkg | 首次安装,交给任何新机器 | installer 不会把隔离属性带给装好的应用,装好后打开**完全没有提示**。已实测:装好的副本只带 com.apple.provenance,没有 com.apple.quarantine。 |
| Shift-macOS-universal.dmg | 软件内升级通道(清单里的 macos 键) | 应用自己下载的副本不带隔离属性,所以软件内升级也不弹窗。若是从浏览器下载再拖进 /Applications,首次打开需要允许一次。 |
所以:新机器装 .pkg,已在用的 Shift 走软件内升级(下载的是 .dmg)。清单的 macos
键必须是 .dmg —— 软件内升级的交接脚本用 hdiutil 挂载镜像再取出应用包,指向 .pkg
会让每次升级都挂载失败。
pkg 里的应用与被拖出来的应用是同一份签名:pkgbuild 既不重新签名也不剥离签名,
内置应用、DMG 内副本、pkg 内副本的 CDHash 完全一致(已核对)。
一台新机器上会看到「身份不明的开发者」提示——这是可以放行的,见下节。
在其它机器上安装
----------------
安装包 .pkg(推荐,新机器)
1. 下载 Shift-macOS-universal.pkg。pkg 本身没有签名(productsign 需要一枚带
Installer Signing 用途的证书,本项目只有代码签名身份),因此浏览器下载后
双击可能被拦:右键 → 打开,或在「系统设置 → 隐私与安全性」中点「仍要打开」,
只需一次,发生在安装之前。
2. 之后按提示安装,载荷会落到 /Applications。
3. 启动 Shift,不会再有任何 Gatekeeper 提示。
终端安装连这一次都不需要:
sudo installer -pkg Shift-macOS-universal.pkg -target /
磁盘镜像 .dmg(新机器,或想手动装)
1. 双击挂载,把 Shift.app 拖进 /Applications。
2. 首次启动被拦:「无法打开,因为来自身份不明的开发者」。点取消后,右键
Shift.app → 打开,或在「系统设置 → 隐私与安全性」中点「仍要打开」。
3. 只需允许一次,之后再打开正常。
新机器首次安装
1. 下载并双击 Shift-macOS-universal.dmg 挂载镜像。
2. 把 Shift.app 拖进「应用程序」(或任何你有权限的位置)。
3. 首次启动会被拦:「无法打开,因为来自身份不明的开发者」。点取消,然后
右键 Shift.app → 打开,或在「系统设置 → 隐私与安全性」中点「仍要打开」。
4. 只需允许一次,之后再打开正常。
macOS 权限
截图与录屏需要「屏幕录制」,输出目录需要「文件与文件夹」,带声音录屏需要
@ -68,16 +53,12 @@ macOS 权限
pnpm install
pnpm mac:drag-bridge
生成通用应用与 DMG,再把应用包包成 .pkg:
生成通用应用与 DMG:
pnpm tauri build --target universal-apple-darwin --bundles app,dmg
scripts/macos-pkg.sh \
src-tauri/target/universal-apple-darwin/release/bundle/macos/Shift.app \
artifacts/Shift-macOS-universal.pkg
scripts/macos-pkg.sh 把应用包暂存到一个 /Applications 根目录下,再用 pkgbuild 打包;
install-location 指向 /Applications,所以这台机器上的每个用户都会装到那里。它用
ditto 而不是 cp,以保留资源分支、符号链接与代码签名。
产物在 src-tauri/target/universal-apple-darwin/release/bundle/macos/ 下:Shift.app
与 Shift-macOS-universal.dmg。发布流程(清单、签名、推送)见仓库 docs/RELEASE.md。
若希望更新通道能校验来源,构建时把 ed25519 公钥编进去(发布流程见仓库
docs/RELEASE.md 的「Signing the channel」):
@ -100,14 +81,9 @@ docs/RELEASE.md 的「Signing the channel」):
# Signature=adhoc
# Identifier=app.nex.shift
安装包本体(pkg 未签名是已知状态,真正的签名在里面的应用上):
pkgutil --check-signature Shift-macOS-universal.pkg # Status: no signature
pkgutil --payload-files Shift-macOS-universal.pkg # ./Shift.app/...
镜像完整性:
hdiutil verify Shift-macOS-universal.dmg
校验后仍打不开的话,请确认不是在压缩包预览窗口里运行的,并优先使用 .pkg;若坚持用
.dmg,按上面的「在其它机器上安装」处理首次允许。
校验后仍打不开的话,请确认不是在压缩包预览窗口里运行的,并按上面的「新机器首次安装」
处理首次允许:右键 → 打开,或在「系统设置 → 隐私与安全性」中点「仍要打开」。

View File

@ -39,8 +39,7 @@ not a code limit, and it decides what the channel may contain:
| Key | Shipped | Notes |
| --- | --- | --- |
| `macos` | yes | One universal bundle, Apple silicon and Intel. The DMG, because that is what the in-app updater mounts |
| — | yes | `Shift-macOS-universal.pkg`, also macOS universal: the file to hand a machine installing Shift for the first time. It carries no manifest key — see "macOS packaging" |
| `macos` | yes | One universal bundle, Apple silicon and Intel, shipped as a DMG. Verified on a fresh machine by dragging it to /Applications — see "macOS packaging" |
| `windows` | yes | x64, which is also what an ARM machine falls back to |
| `windows-arm64` | no | Buildable — `build-windows-release.sh --arch arm64` still works — just not published |
| `linux` | no | Build target, not a product; see below |
@ -99,32 +98,32 @@ project wants, and no release is worse off for losing a certificate no other Mac
Reusing that identity again would mean installing it **and trusting it** on every machine,
which is not something to ask of a user.
So: ad-hoc, and the two containers each cover one job.
So: ad-hoc, and one container. The channel ships **`Shift-macOS-universal.dmg`** and nothing
else on macOS — the earlier `.pkg` companion was dropped after the DMG was verified to work
on a fresh machine, and one file per platform is less to keep straight.
| Container | First launch on a fresh machine |
| Situation | What happens |
| --- | --- |
| `.pkg`, via Installer.app or `installer` | `installer` does not propagate quarantine onto what it installs, so the app opens with **no prompt at all**. Verified: an installed copy carries `com.apple.provenance` and no `com.apple.quarantine`. The package itself is unsigned (`productsign` needs an *Installer Signing* certificate; a code-signing identity is rejected), so a browser-downloaded package may need right-click → 打开 once, before anything installs. `installer -pkg … -target /` needs nothing. |
| `.dmg`, app dragged to /Applications | The app keeps the browser's quarantine flag, so the first launch needs the one approval above. Shift's own downloader sets no quarantine flag, which is why **in-app updates never prompt** — only a browser download on a new machine does. |
| A machine installing Shift for the first time | Double-click the DMG, drag `Shift.app` to /Applications. The app keeps the browser's quarantine flag, so the **first launch** needs the one approval above: right-click → 打开, or 允许 in 系统设置 → 隐私与安全性. Every launch after that is normal. |
| An installed Shift updating itself | `update_install`'s handoff downloads the DMG, mounts it with `hdiutil`, copies the bundle out and drops the quarantine flag. Shift's own downloader sets no quarantine flag (`curl` sets none, and the handoff strips it anyway), so **in-app updates never prompt**. |
`scripts/macos-pkg.sh <Shift.app> <out.pkg>` builds the package: it stages the bundle under
an `/Applications` root and runs `pkgbuild`, which neither re-signs nor strips the payload —
the CDHash is identical in the built bundle, the DMG copy and the pkg copy.
The `macos` manifest key is a DMG for the same reason: the in-app handoff mounts the image,
so pointing the key at a package would break every in-app update. That was the one real
constraint the container had to satisfy, and a DMG satisfies it.
The `macos` manifest key stays a DMG on purpose: `update_install`'s handoff mounts the image
with `hdiutil` and copies the bundle out of it, so pointing the key at a `.pkg` would make
every in-app update fail to mount.
`scripts/macos-pkg.sh` — which staged the bundle under an `/Applications` root and ran
`pkgbuild` — is kept in the tree but is no longer part of a release: it built a container
with no manifest key, and the DMG covers the first install anyway.
Closing this for good means an Apple Developer ID: `Developer ID Application` +
`notarytool` + `stapler staple`. Then both containers open on double-click with no pane to
visit, and Screen Recording approval stops resetting between builds because the identity
stops changing.
`notarytool` + `stapler staple`. Then the DMG opens on double-click with no pane to visit,
and Screen Recording approval stops resetting between builds because the identity stops
changing.
## Publishing
```bash
pnpm tauri build --target universal-apple-darwin --bundles app,dmg
scripts/macos-pkg.sh src-tauri/target/universal-apple-darwin/release/bundle/macos/Shift.app \
artifacts/Shift-macOS-universal.pkg # the first-install container
printf 'Fixes the ring on external displays.\n' > /tmp/notes.md
scripts/publish-release.sh --notes /tmp/notes.md # hash, commit, push
```
@ -145,19 +144,17 @@ same Python pass that walks the files produces both.
Recognised installers: `Shift-macOS-universal.dmg` (macOS), `Shift-Setup-<version>-win-x64.exe`
and `Shift-Setup-<version>-win-arm64.exe` (Windows, keys `windows` and `windows-arm64`),
`*.AppImage` / `*.deb` (Linux). Other files in `artifacts/` — the macOS `.pkg`, the portable
ZIPs, `SHA256SUMS.txt`, the `README-Windows-<arch>.txt` notes and
`README-macOS-universal.txt` — the packaging note that explains the ad-hoc signature, what a
fresh machine does with each container, and how to verify a download — travel with the
branch and are downloadable from it, but are not offered as installers by the manifest. The
`.pkg` carries no key on purpose: the `macos` key must stay a DMG so the in-app handoff can
mount it ("macOS packaging"). Dotfiles and an old manifest are skipped.
`*.AppImage` / `*.deb` (Linux). Other files in `artifacts/` — the portable ZIPs,
`SHA256SUMS.txt`, the `README-Windows-<arch>.txt` notes and `README-macOS-universal.txt`,
the packaging note explaining the ad-hoc signature and how to verify a download — travel
with the branch and are downloadable from it, but are not offered as installers by the
manifest. Dotfiles and an old manifest are skipped.
`README-macOS-universal.txt` is tracked in the repository as well as pushed to the channel,
so the scheme is documented where a contributor reads it and not only next to a build
product. Every claim in it was checked against the shipped artifacts: the installed
`.pkg`'s payload is `Signature=adhoc`, `pkgutil --check-signature` reports `no signature`
for the package itself, and `shasum -a 256 -c SHA256SUMS.txt` passes on the published set.
product. Every claim in it was checked against the shipped artifacts: the bundle inside the
published DMG is `Signature=adhoc`, and `shasum -a 256 -c SHA256SUMS.txt` passes on the
published set.
Both Windows architectures come from one command, which cross-compiles each target,
checks the PE machine field of the binary it just built (`0x8664` for x64, `0xAA64` for
@ -340,8 +337,9 @@ than trusting the local copy:
| `windows-arm64` | not published | by choice — see "Supported release targets" |
| `linux` | not published | by choice: Linux is a build target here, not a shipped product |
`Shift-macOS-universal.pkg` sits on the same branch with no manifest key, for first installs
("macOS packaging"); it was hashed the same way and downloaded back to check.
The 0.1.3 tree still carries the retired `Shift-macOS-universal.pkg`, because removing it
means re-publishing; it has no manifest key, so no client can be served it, and it is simply
not built any more ("macOS packaging"). macOS ships one artifact from the next publish on.
`shift-update.sig` verifies over the manifest's exact bytes against the key baked into both
artifacts. The channel's home is derived from `origin` at build time, and this forge is

View File

@ -108,12 +108,13 @@ names what is still missing.
signing with a locally created certificate made every other machine refuse the app as
*damaged / malware* with no override, because that certificate cannot chain to a trusted
root anywhere else, while an ad-hoc binary gets the softer "unidentified developer" box
the user can approve. The channel also publishes `Shift-macOS-universal.pkg`, since
`installer` does not leave the installed copy quarantined and the app then opens with no
prompt at all. The `macos` manifest key stays a DMG so the in-app handoff can keep
mounting it; see "macOS packaging" in `docs/RELEASE.md`. A Developer ID plus notarization
removes the prompt entirely and would also stop Screen Recording approval from resetting
between builds.
the user can approve. The channel ships one macOS container, the DMG: it was verified on a
fresh machine (drag to /Applications, one approval on first launch), so the `.pkg` that
once accompanied it was dropped rather than kept as a second thing to maintain. The `macos`
manifest key has to stay a DMG anyway, because the in-app handoff mounts it with `hdiutil`;
see "macOS packaging" in `docs/RELEASE.md`. A Developer ID plus notarization removes the
prompt entirely and would also stop Screen Recording approval from resetting between
builds.
- Signed Windows installer: pending.
- Manifest signing is done. `scripts/release-key.py` mints the release key,
`publish-release.sh --key` publishes a detached `shift-update.sig` over the manifest's