Quden Dev Doc

Appearance

Desktop Application Mac 開発 ​

macOS における Desktop Application の開発について記載しています。

ローカル開発 ​

ローカル開発環境を開始する前に、下記のコマンドを実行して Native module を事前にビルドしておく必要があります。

ビルド時の環境条件:

  • Node.js v20.x
  • Python v3.11.x
bash
# x64 architecture (mac, Intel) の場合
yarn run build-addons:x64:mac

# arm64 architecture (mac, M1/M2) の場合
yarn run build-addons:arm64

ローカル開発環境を開始するには、下記のコマンドを実行します。

bash
# ローカル開発
yarn run start

# staging 環境を用いた開発
yarn run start:staging

# production 環境を用いた開発
yarn run start:prod

それぞれのコマンドは、各環境ごとに用意された .env.[development|staging|prod] ファイルを読み込みます。 ファイルが存在しない場合は随時作成してください。

下記に、各環境で利用する .env ファイルの内容を示します。

bash
# .env.development
APP_ENV_NAME="development"
bash
# .env.staging
BASIC_AUTH_USERNAME="<BASIC 認証のユーザー名を記入してください>"
BASIC_AUTH_PASSWORD="<BASIC 認証のパスワードを記入してください>"
APP_ENV_NAME="staging"
bash
# .env.production
APP_ENV_NAME="production"

Package されたアプリのログを見る方法 ​

Electron 内のログは electron-log というモジュールを利用しています。

logger.info() などの関数を利用することでログを出力することができ、出力先は下記の通り設定されています。

  • コンソール
  • ファイル
    • ~/Library/Logs/Quden/main.log (macOS)

ファイルに保存されたログを見る際は、下記コマンドを実行することでログをリアルタイムに表示することができます。

bash
# mac
tail -f ~/Library/Logs/Quden/main.log

カメラやマイクの許可設定をリセットする方法 ​

カメラやマイクなどの権限がなかったときの挙動を確かめたい場合、カメラやマイクの許可設定をリセットする必要があります。

カメラやマイクの許可設定のリセットは、画面収録許可などとは異なり、GUI 上からおこなうことができません。 下記コマンドを実行して、許可設定をリセットしてください。

bash
# カメラの許可設定をリセットする
tccutil reset Camera io.quden.Quden

# マイクの許可設定をリセットする
tccutil reset Microphone io.quden.Quden

io.quden.Quden は、アプリの Bundle ID (appBundleId) です。

yarn run start などで開発している際は、下記のコマンドを実行することで、アプリの Bundle ID を確認することができます。

bash
lsappinfo info -only bundleid <app_name>

# VSCode の場合
lsappinfo info -only bundleid "Visual Studio Code"

# Warp の場合
lsappinfo info -only bundleid Warp
# -> "CFBundleIdentifier"="dev.warp.Warp-Stable"

ビルド ​

事前準備 ​

macOS のビルドにおいて必要な事前準備は、大きく4つあります。

  • 0: Apple Developer Program への登録
  • 1: Xcode のインストール
  • 2: Signing certificates (コードサイニング証明書) の発行
  • 3: Notarization (アプリの公証) 用 key の発行

公式ドキュメントは下記リンクを参照してください。

0: Apple Developer Program への登録 ​

各種証明書の発行には、Apple Developer Program への登録が必要です。すでに zipunk のアカウントがあるため、そちらを利用して証明書を発行します。

各開発者は、管理者に zipunk アカウントへ招待をしてもらってください。

1: Xcode のインストール ​

Xcode をインストールしてください。App Store からインストールできます。

2: Signing certificates (コードサイニング証明書) の発行 ​

Signing certificates 発行の流れは下記のとおりです。

  • 1: Xcode を起動する
  • 2: Apple Developer Program に登録されている Apple ID でサインインする
  • 3: こちら の手順に従って下記2つの証明書を発行する
    • Developer ID Application
    • Developer ID Installer

発行されていることは、下記のような画面で確認できます。

xcode

また、下記のコマンドを実行して、証明書の存在を確認することもできます。

bash
security find-identity -p codesigning -v
#   1) XXXXXXXXXXXXXXXXXXX "Developer ID Application: ZIPUNK, INC. (XXXXXXXXXXX)"
#     1 valid identities found

3: Notarization (アプリの公証) 用 key の発行 ​

Notarization 用の key を発行するためには、下記の手順に従ってください。

  • 1: Apple Developer Program に登録済みのアカウントでログインする
  • 2: 「App Store Connect > ユーザーとアクセス > キー」のページにアクセスする
  • 3: 「＋」ボタンからキーを発行し、秘密鍵 (*.p8) を保存する
    • ついでに APPLE_API_ISSUER と APPLE_API_KEY_ID も控えておく

App Store Connect

  • 4: 保存した秘密鍵を ./certifications/ 配下に保存する
  • 5: .env.build 内に下記のように環境変数を設定する
bash
# .env.build
APPLE_API_KEY="./certifications/hoge.p8"
APPLE_API_KEY_ID="<APPLE_API_KEY_ID>"
APPLE_API_ISSUER="<APPLE_API_ISSUER>"
GITHUB_TOKEN="<Personal Access Token を入れる>"

以上で、macOS でのビルドに必要な事前準備は完了です。次に実際にビルドを行います。

ビルドコマンド ​

ビルドは、下記のコマンドを実行することで行うことができます。

bash
# mac で x64 architecture のアプリをビルドする
yarn run make:x64:mac:prod

# windows で x64 architecture のアプリをビルドする
yarn run make:x64:win:prod

# arm64 architecture のアプリをビルドする
yarn run make:arm64:prod

💡 yarn run make の実体は electron-forge make です。このコマンドは、packaging と make の2つの処理を行ってくれます。(つまり、yarn run package を内包しています。)

実行が正常に完了すると、以下のようなログが出力され、out/make 配下にビルド成果物が作成されます。

text
$ yarn run make
yarn run v1.22.19
warning package.json: No license field
$ npx dotenv-cli -e .env -- electron-forge make
✔ Checking your system
✔ Loading configuration
✔ Resolving make targets
  › Making for the following targets: zip
✔ Running package command
  ✔ Preparing to package application
  ✔ Running packaging hooks
    ✔ Running generateAssets hook
    ✔ Running prePackage hook
      ✔ [plugin-webpack] Preparing native dependencies
      ✔ [plugin-webpack] Building webpack bundles
  ✔ Packaging application
    ✔ Packaging for arm64 on darwin [2m11s]
  ✔ Running postPackage hook
✔ Running preMake hook
✔ Making distributables
  ✔ Making a zip distributable for darwin/arm64 [6s]
✔ Running postMake hook
  › Artifacts available at: /path/to/quden-desktop-app/out/make
✨  Done in 150.54s.

ビルド時のエラー ​

Python のバージョン ​

下記のようなエラーが発生することがあります。(参考: slack)

text
Traceback (most recent call last):
  File "/Users/masatakaushijima/development/work/zipunk/quden-desktop-app/node_modules/node-gyp/gyp/gyp_main.py", line 42, in <module>
    import gyp  # noqa: E402
    ^^^^^^^^^^
  File "/Users/masatakaushijima/development/work/zipunk/quden-desktop-app/node_modules/node-gyp/gyp/pylib/gyp/__init__.py", line 9, in <module>
    import gyp.input
  File "/Users/masatakaushijima/development/work/zipunk/quden-desktop-app/node_modules/node-gyp/gyp/pylib/gyp/input.py", line 19, in <module>
    from distutils.version import StrictVersion
ModuleNotFoundError: No module named 'distutils'

このエラーは、Python のバージョンが 3.12 以上であることが原因です(参考)。3.11 に下げて実行することで解決します。 または distutils モジュールをインストールすることで解決することができます（未検証）。

Python のバージョン管理 ​

Python のバージョン管理方法はいろいろありますが、一例として以下を使う方法があります。

  • pyenv を使って Python のバージョンを管理する
  • venv を使って仮想環境を作成する
    • ※ ビルドにおいては仮想環境を作成する必要が無いので、ここでは利用しません

まず brew で pyenv をインストールします。

bash
brew update
brew install pyenv

その後 pyenv 用のパス設定に関する処理を .zshrc などに追記します。

bash
# .zshrc
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

pyenv で Python のバージョンをインストールします。

bash
# addons のビルドには 3.11 が必要
pyenv install 3.11

pyenv でインストールした Python のバージョンを指定して仮想環境を作成します。

bash
pyenv local 3.11

配布 ​

macOS アプリの配布の大まかな流れは以下のとおりです。

  1. 事前準備をする
  2. Version を更新する
  3. Publish コマンドを実行する

続くセクションで詳しく説明します。

公式ドキュメントは下記を参照してください：

配布の事前準備 ​

事前準備は大きく2つあります。

  • アプリのビルド
  • GITHUB_TOKEN の取得

アプリのビルドに関してはアプリのビルドを参照してください。

GITHUB_TOKEN は、GitHub の Personal Access Token を利用します。 下記の手順に従って、Personal Access Token を取得してください。

Token settings

sh
# .env.build file
APPLE_API_KEY="..."
APPLE_API_KEY_ID="..."
APPLE_API_ISSUER="..."
GITHUB_TOKEN="<TOKEN_HERE>"

Publish ​

Publish は、下記のコマンドを実行することで行うことができます。

bash
# WARN: yarn publish と間違えないことに注意してください！！

# mac で x64 architecture のアプリをビルドし、配布可能な形に変換する (dry run)
yarn run publish:x64:mac:prod:dry-run

# mac で dry run において生成したアーティファクトを、GitHub にアップロードする
yarn run publish:x64:mac:prod:from-dry-run

publish コマンドが正常に終了すると、↓のリンクで新しい version が公開されていることを確認できます。

また、zipunk/quden-desktop-app-update-server 内の release にも、新しい version が公開されていることを確認できます。