From 75535e3013c210e69ff899ed047afc7d146fe120 Mon Sep 17 00:00:00 2001 From: fengfeng-zi Date: Sun, 26 Apr 2026 17:00:55 +0800 Subject: [PATCH 1/2] docs: add macOS install guide --- docs/install-macos.md | 80 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 docs/install-macos.md diff --git a/docs/install-macos.md b/docs/install-macos.md new file mode 100644 index 0000000..83591ca --- /dev/null +++ b/docs/install-macos.md @@ -0,0 +1,80 @@ +# macOS Installation Guide + +This guide explains how to build and package the macOS client from source. + +## Who this is for + +- New contributors who want to run the macOS client locally. +- Maintainers who need to generate a `.dmg` package. + +## Before you start + +- macOS `15.0+` +- Apple Silicon (`arm64`) +- Xcode `15+` **or** an equivalent Swift toolchain +- Swift `5.9+` + +Check your environment: + +```bash +sw_vers +uname -m +xcodebuild -version +swift --version +``` + +## 1) Go to the macOS client directory + +```bash +cd platforms/macos/client +``` + +## 2) Build the app + +Choose one of the supported entry points: + +```bash +swift build -c release --arch arm64 --product AhaKeyConfig +``` + +or + +```bash +bash scripts/build.sh +``` + +or + +```bash +make build +``` + +## 3) Run local verification + +After building, confirm the build completes without errors and expected outputs are produced under Swift build artifacts. + +## 4) Package as `.dmg` (optional) + +Use one of the current packaging scripts: + +```bash +bash scripts/package_dmg.sh +``` + +or + +```bash +bash scripts/release_dmg.sh +``` + +## Notes + +- Release binaries such as `.app` and `.dmg` are **not** committed to this repository. +- The macOS build and release process is still being standardized; script behavior may evolve. +- For end users, installation packages are distributed through GitHub Releases. + +## Quick troubleshooting + +- `swift` not found: install Xcode Command Line Tools or a Swift toolchain. +- Wrong architecture: confirm `uname -m` returns `arm64`. +- Build script permission issues: run `chmod +x scripts/*.sh` and retry. From 3e737c32d482fc6eb296e1495d63d25a2ca0b39f Mon Sep 17 00:00:00 2001 From: fengfeng-zi Date: Wed, 29 Apr 2026 17:39:06 +0800 Subject: [PATCH 2/2] docs: fold macOS install guide into existing docs --- docs/install-macos.md | 80 --------------------------------------- docs/installation.md | 1 + platforms/macos/README.md | 10 +++++ 3 files changed, 11 insertions(+), 80 deletions(-) delete mode 100644 docs/install-macos.md diff --git a/docs/install-macos.md b/docs/install-macos.md deleted file mode 100644 index 83591ca..0000000 --- a/docs/install-macos.md +++ /dev/null @@ -1,80 +0,0 @@ -# macOS Installation Guide - -This guide explains how to build and package the macOS client from source. - -## Who this is for - -- New contributors who want to run the macOS client locally. -- Maintainers who need to generate a `.dmg` package. - -## Before you start - -- macOS `15.0+` -- Apple Silicon (`arm64`) -- Xcode `15+` **or** an equivalent Swift toolchain -- Swift `5.9+` - -Check your environment: - -```bash -sw_vers -uname -m -xcodebuild -version -swift --version -``` - -## 1) Go to the macOS client directory - -```bash -cd platforms/macos/client -``` - -## 2) Build the app - -Choose one of the supported entry points: - -```bash -swift build -c release --arch arm64 --product AhaKeyConfig -``` - -or - -```bash -bash scripts/build.sh -``` - -or - -```bash -make build -``` - -## 3) Run local verification - -After building, confirm the build completes without errors and expected outputs are produced under Swift build artifacts. - -## 4) Package as `.dmg` (optional) - -Use one of the current packaging scripts: - -```bash -bash scripts/package_dmg.sh -``` - -or - -```bash -bash scripts/release_dmg.sh -``` - -## Notes - -- Release binaries such as `.app` and `.dmg` are **not** committed to this repository. -- The macOS build and release process is still being standardized; script behavior may evolve. -- For end users, installation packages are distributed through GitHub Releases. - -## Quick troubleshooting - -- `swift` not found: install Xcode Command Line Tools or a Swift toolchain. -- Wrong architecture: confirm `uname -m` returns `arm64`. -- Build script permission issues: run `chmod +x scripts/*.sh` and retry. diff --git a/docs/installation.md b/docs/installation.md index 0e0850e..f36d2e1 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -49,6 +49,7 @@ ### macOS client - 目录：`platforms/macos/client/` +- 详细安装/构建说明：参见 `platforms/macos/README.md` 与 `platforms/macos/client/README.md` - 当前可判断的环境要求： - macOS 15.0+ - Xcode 15+ 或等效 Swift toolchain diff --git a/platforms/macos/README.md b/platforms/macos/README.md index 4ad6206..3bb41f6 100644 --- a/platforms/macos/README.md +++ b/platforms/macos/README.md @@ -47,6 +47,11 @@ The macOS baseline is still in an early post-migration state. Source, project fi - Historical macOS repositories may be retained temporarily during migration - macOS source is kept separate from Windows code and is not mixed into `platforms/windows/` +### Installation docs + +- Repository-level installation overview: `docs/installation.md` +- macOS client build/package details: `platforms/macos/client/README.md` + --- # 简体中文 @@ -93,3 +98,8 @@ macOS 客户端源码已迁入 `platforms/macos/client/`。 - macOS 安装包应通过 GitHub Releases 分发 - 迁移过程中，历史 macOS 仓库可能会暂时保留 - macOS 源码不会混入 `platforms/windows/` + +### 安装文档入口 + +- 仓库级安装总览：`docs/installation.md` +- macOS 客户端构建与打包细节：`platforms/macos/client/README.md`