# [メタ情報]
# 識別子: LaunchAgentのplistの解説_exe
# システム名: 未分類
# 技術種別: Misc
# 機能名: Misc
# 使用言語: []
# 状態: 実行用
# [/メタ情報]
LaunchAgent の plist 基本解説
================================
1. plist とは何をするファイルか
================================
・plist は「Property List」の略で、macOS が設定情報を読むためのファイル形式です。
・中身は XML という書式で書かれています。
・LaunchAgent の plist は、
→ どのスクリプトを
→ いつ（どのタイミングで）
→ どのユーザー権限で
動かすかを macOS に伝える「ジョブ定義書」のような役割を持ちます。
================================
2. LaunchAgent と plist の置き場所
================================
■ ユーザーごとの自動実行（LaunchAgent）
・保存場所：
~/Library/LaunchAgents/
（ホームフォルダの中の Library/LaunchAgents）
・ここに置いた plist は、
そのユーザーがログインしているときだけ有効です。
・バックアップ用の rsync スクリプトなど、
普段ログインして使っているユーザーで動かしたい処理は、
LaunchAgent を使う形で十分です。
■ システム全体用（LaunchDaemon）
・場所は /Library/LaunchDaemons/ ですが、
管理が少し難しくなるため、ここでは扱いません。
・通常のバックアップ用途なら、ユーザーごとの LaunchAgent で問題ありません。
================================
3. plist の基本構造（最低限おさえたい形）
================================
LaunchAgent 用 plist の最小構成は、概ね次のようになります。
・ファイルの雰囲気（イメージ）：
Label
com.example.jobname
ProgramArguments
/bin/bash
/Users/ユーザー名/scripts/test.sh
StartCalendarInterval
Hour2
Minute30
ここで特に重要なのは次の 3 つです。
(1) Label … ジョブの識別名
(2) ProgramArguments … 実行するコマンド（スクリプト）とその引数
(3) StartCalendarInterval … いつ実行するか（時間の指定）
================================
4. 各要素の詳しい説明
================================
-----------------------------
4-1. Label（ラベル）
-----------------------------
・この LaunchAgent ジョブの「名前」です。
・launchctl コマンドで状態を確認するときに、この名前が表示されます。
・一般的には「ドメイン名を逆にしたもの＋用途名」のような形式にします。
例：
com.xxxxxxm1.tanada_T0_to_T1
com.xxxxxxm1.sync_scripts_pub
自分が見て意味が分かればよいので、厳密な決まりはありません。
-----------------------------
4-2. ProgramArguments（実行コマンド）
-----------------------------
・実行したいプログラムと引数を「配列（array）」の形で並べます。
・1つの が 1 引数分です。
・シェルの一行コマンドをそのまま書くのではなく、分割して書くイメージです。
例：bash のスクリプトを実行する場合
ProgramArguments
/bin/bash
/Users/xxxxxxm1/scripts/tanada/sync_T0_to_T1_main.sh
ポイント：
・パスは「絶対パス」で書きます。
・PATH 環境変数はあまり信用できないので、
スクリプト側でも /opt/homebrew/bin/rsync のように絶対パスを指定すると安心です。
-----------------------------
4-3. StartCalendarInterval（時間指定）
-----------------------------
・「何時に動かすか」を指定する場所です。
・dict（連想配列）の中に Hour / Minute などを書きます。
■ 毎日 2:30 に実行する例：
StartCalendarInterval
Hour2
Minute30
・Hour は 0〜23（24時間形式）
・Minute は 0〜59
■ もう少し複雑な指定も可能です：
・Weekday（曜日） … 1=日曜, 2=月曜, …, 7=土曜
・Day（その月の何日） … 1〜31
・Month（何月） … 1〜12
複数パターンで起動したい場合は、dict を配列にして複数書くこともできますが、
通常の毎日バックアップなら「Hour + Minute」の 1セットで十分です。
================================
5. よく使う追加オプション
================================
-----------------------------
5-1. RunAtLoad
-----------------------------
・Mac にログインしたタイミングでも実行したい場合に使います。
RunAtLoad
・例：
・通常は毎日 2:30 に起動
・さらに、Mac を再起動／ログインしたときにも一度動かしたい
といったケース。
-----------------------------
5-2. StandardOutPath / StandardErrorPath
-----------------------------
・スクリプトの実行結果（標準出力、標準エラー）をファイルに保存するための設定です。
・トラブルが起きた時に原因を追えるように、できるだけ設定しておくことをおすすめします。
例：
StandardOutPath
/Users/xxxxxxm1/scripts/logs_tanada/job.out
StandardErrorPath
/Users/xxxxxxm1/scripts/logs_tanada/job.err
・あらかじめ logs 用フォルダを作成しておきます：
mkdir -p ~/scripts/logs_tanada
-----------------------------
5-3. StartInterval（秒ごとの実行）
-----------------------------
・「◯秒ごとに実行したい」ときに使います。
例：1時間ごと（3600秒ごと）に実行する場合：
StartInterval
3600
・StartCalendarInterval（時刻指定）とは併用しない方が分かりやすいです。
（どちらか一方だけにするのが一般的）
================================
6. plist の保存・有効化・確認
================================
-----------------------------
6-1. 保存場所
-----------------------------
・ユーザーごとの LaunchAgent の場合：
~/Library/LaunchAgents/（ここに xxx.plist を保存）
例：
/Users/xxxxxxm1/Library/LaunchAgents/com.xxxxxxxxm1.tanada_T0_to_T1.plist
-----------------------------
6-2. 有効化（ロード）
-----------------------------
・ターミナルで次のように実行します：
launchctl load ~/Library/LaunchAgents/com.xxxxxxm1.tanada_T0_to_T1.plist
・正常なら特に何も表示されません。
-----------------------------
6-3. 無効化（アンロード）
-----------------------------
launchctl unload ~/Library/LaunchAgents/com.xxxxxxm1.tanada_T0_to_T1.plist
-----------------------------
6-4. 動作確認
-----------------------------
launchctl list | grep tanada
・ここで、Label に指定した名前が表示されていれば、
ジョブとして登録されています。
================================
7. よくあるトラブルと確認ポイント
================================
(1) パスの間違い
・ProgramArguments で指定したスクリプトのパスが誤っていると実行されません。
・絶対パス（/Users/…から始まる形）で書かれているか確認します。
(2) スクリプトに実行権限がない
・シェルスクリプトを作成したら、次のコマンドで実行権限を付けます：
chmod +x /Users/xxxxxxm1/scripts/tanada/sync_T0_to_T1_main.sh
(3) plist の XML が壊れている
・タグの閉じ忘れなどがあると、launchctl load がうまくいきません。
・次のコマンドで文法チェックができます：
plutil ~/Library/LaunchAgents/com.xxxxxxm1.tanada_T0_to_T1.plist
(4) ログを見て原因を探す
・StandardOutPath / StandardErrorPath に指定したファイルを開き、
エラー内容を確認します。
================================
8. まとめ（考え方の整理）
================================
・LaunchAgent の plist は、
「いつ・何を動かすか」を macOS に伝えるスケジュール表
のようなものです。
・一方で、実際の処理内容（どのフォルダを rsync するか、ログをどう書くか等）は、
→ シェルスクリプト側（例：sync_T0_to_T1_main.sh）
に詳しく書きます。
・役割分担をまとめると：
● plist（LaunchAgent）
- Label（ジョブ名）
- ProgramArguments（どのスクリプトを動かすか）
- StartCalendarInterval / StartInterval（いつ動かすか）
- ログの保存先（StandardOutPath / StandardErrorPath）
● シェルスクリプト
- rsync のオプション
- コピー元・コピー先のパス
- エラー処理や、必要ならメール通知など