CocoaPods Trunk：概要、Trunkを使ったライブラリの公開

CocoaPods Trunkとは？

CocoaPods Trunkは、podライブラリの集中公開のために2015年に開始されたサーバーインフラストラクチャです。Trunk以前は、各podはGitリポジトリを介して配布されていました。開発者は公開リポジトリを作成し、podspecファイルを追加し、中央リポジトリCocoaPods/SpecsにPull Requestを送信する必要がありました。このアプローチには手動のモデレーションが必要で、更新の公開に遅延が生じていました。

Trunkは、公開、更新、pod管理のための統一APIを提供することでこれらの問題を解決しました。このサービスには4つの主要コンポーネントがあります。

• 認証 — メール確認付きの登録とセッショントークン管理。各開発者は、アカウントとデバイスにリンクされた一意のトークンを取得します。
• 検証 — 構文解析、依存関係リンティング、プラットフォーム互換性チェックを含む、公開前のpodspecの自動検証。
• ホスティング — CocoaPodsサーバーでのpodメタデータとバージョンの保存。ソースコードは開発者のGitリポジトリに残り、Trunkはpodspecファイルとリンクのみを保存します。
• アクセス管理 — pod所有者の追加と削除、公開権限の譲渡、podの非推奨マーク付け。

Trunkのアーキテクチャは、PostgreSQLデータベースを備えたRuby on Railsスタック上に構築されています。このサービスはすべての操作にJSON形式のHTTP APIを使用し、CLIクライアントpod trunkはCocoaPodsディストリビューションの一部で、メインのcocoapodsgemと共にインストールされます。

現在までに、Trunkを通じて10万以上のpodが公開され、総ダウンロード数は500億を超えています。このサービスは、世界中の開発者から毎日数千の公開および更新リクエストを処理しています。

登録と認証

podを公開する前に、Trunkに登録する必要があります。プロセスは1つのステップで構成されています — pod trunk registerコマンドです。

pod trunk register your@email.com 'Your Name' --description='MacBook Pro、iOS開発'

コマンドを実行すると、指定されたメールに確認リンクが送信されます。リンクをクリックするとアカウントが有効になり、システムキーチェーン（macOSのKeychain、Linuxのgnome-keyringまたは同等）に保存されるセッショントークンが作成されます。このトークンは、後続のすべてのpod trunk操作で自動的に使用されます。

--descriptionパラメータはオプションですが推奨されます — pod trunk meでアクティブセッションを表示する際にセッションを識別するのに役立ちます。複数のマシン（ワークステーション、CIサーバー）で作業する場合、説明によってセッションを区別できます。

認証ステータスを確認するには、次のコマンドを使用します。

pod trunk me

出力には、メール、名前、podリスト（公開済みの場合）、アクティブセッションが表示されます。結果の例：

  - Name: Your Name
  - Email: your@email.com
  - Since: 2024-03-15 10:30 UTC
  - Pods:
    - MyLibrary
    - AnotherPod
  - Sessions:
    - 2024-03-15 10:30 UTC - MacBook Pro、iOS開発

CIサーバー（GitHub Actions、GitLab CI、Jenkins）では、COCOAPODS_TRUNK_TOKEN環境変数を介して渡されるトークンを使用して認証が行われます。トークンは次のコマンドで取得できます。

pod trunk me --token-only

このトークンはCI設定に秘密変数として保存され、再登録なしで公開ステップで使用されます。GitHub Actionsの例：

env:
  COCOAPODS_TRUNK_TOKEN: ${{ secrets.COCOAPODS_TRUNK_TOKEN }}

重要：トークンはアカウントにリンクされたpodの管理への完全なアクセスを提供します。公開リポジトリで公開したり、第三者と共有したりしないでください。漏洩した場合は、pod trunk remove-sessionを介して、またはCocoaPodsウェブサイトのコントロールパネルからすべてのセッションを削除してトークンを無効化できます。

Podspecの準備

podspecファイル（.podspecまたは.podspec.json）は、メタデータ、依存関係、プラットフォーム情報、ソースコードの詳細を含むライブラリのマニフェストです。Trunkはこのファイルをpodの検証と登録に使用します。公開のための最小限のpodspecは次のようになります。

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'ライブラリの簡単な説明'
  s.description  = '機能の説明付きの詳細な説明'
  s.homepage     = 'https://github.com/username/MyLibrary'
  s.license      = { :type => 'MIT', :file => 'LICENSE' }
  s.author       = { 'Your Name' => 'your@email.com' }
  s.source       = { :git => 'https://github.com/username/MyLibrary.git', :tag => s.version.to_s }
  s.source_files = 'Sources/**/*.{swift,h,m}'
  s.platform     = :ios, '12.0'
  s.swift_version = '5.7'
end

podspecの主要フィールド：

• name — pod名。Trunkレジストリ内で一意である必要があります。名前は先着順で登録されます — 名前が既に使用されている場合、公開は拒否されます。
• version — MAJOR.MINOR.PATCH形式のセマンティックバージョン。Trunkは同じバージョンの再公開を許可しません — 番号を増やす必要があります。
• source — Gitリポジトリのリンクとタグ。Trunkはソースコードを保存しないため、リポジトリはクローン可能である必要があります。
• platform — ターゲットプラットフォーム（iOS、macOS、tvOS、watchOS）と最小SDKバージョン。
• license — ライセンスの種類。MIT、Apache-2.0、BSDなどのオープンソースライセンスを指定することを推奨します。

公開前に、リンターでpodspecの正確性を確認します。

pod lib lint MyLibrary.podspec

リンターは構文、必須フィールド、ファイルパスの正確性、依存関係の解決可能性をチェックします。リンティングプロセスでプライベートソースを使用する場合は、--sourcesフラグを追加します。ネットワークダウンロードをスキップするには（ローカルチェックのみ）、--local-onlyフラグを使用します。

pod trunk pushによる公開

podを公開するためのメインコマンドはpod trunk pushです。これはpodspecファイルをTrunkサーバーに送信し、完全な検証を受けてパブリックレジストリに登録されます。構文：

pod trunk push MyLibrary.podspec

--allow-warningsフラグは、警告があっても公開を許可します。デフォルトでは、警告があると公開がブロックされます。ライブラリに機能に影響しない既知の警告がある場合、このフラグを使用できます。重要：エラーはフラグに関係なく常に公開をブロックします。

--synchronousフラグはリクエストを同期的にします — ターミナルはサーバー側の検証が完了するのを待ちます。デフォルトでは、コマンドは送信後すぐに制御を返し、サーバーは非同期的に公開を処理します。同期モードは、パイプラインの次のステップが公開の成功に依存するCI/CDで役立ちます。

--skip-import-validationフラグは、テストプロジェクトへのライブラリインポートのチェックをスキップします。これにより公開が高速化されますが、ライブラリが実際にコンパイルされることは保証されません。このフラグは、ビルドの正確性に自信がある場合にのみ使用してください。

一般的なオプションを使用した公開の例：

pod trunk push MyLibrary.podspec \
  --allow-warnings \
  --synchronous \
  --skip-import-validation

公開が成功すると、Trunkは詳細を含むJSONを返します。

  Congrats

  MyLibrary (0.1.0) successfully published

  Pod URL: https://cocoapods.org/pods/MyLibrary

ライブラリは、任意のiOSまたはmacOSプロジェクトでPodfileを介してインストールできるようになります。通常、CocoaPodsの検索インデックスは数分以内に更新されますが、まれにインデックス作成に最大1時間かかる場合があります。

重要な制限：一度公開されたpodバージョンは削除できません。これは、このバージョンを既に使用しているプロジェクトを壊さないためです。公開に誤りがあった場合は、修正を加えた次のバージョンを公開できますが、ロールバックは不可能です。例外はpod trunk deleteで、CocoaPodsスタッフのみが利用でき、極端な場合（ライセンス違反、悪意のあるコード）に使用されます。

リリースとアクセス管理

CocoaPods Trunkは、公開されたpodを管理するためのいくつかのコマンドを提供します。

所有者の追加

別の開発者にpodの公開権限を譲渡するには、次のコマンドを使用します。

pod trunk add-owner MyLibrary developer@email.com

実行後、新しい所有者はpod管理への完全なアクセス権を取得します：新しいバージョンの公開、他の所有者の追加と削除、podの非推奨マーク付け。登録済みのTrunkユーザーであれば誰でも所有者になれます — 事前登録が必要です。

所有者の削除

開発者がプロジェクトを離れた場合やpodへのアクセス権を持つべきでない場合：

pod trunk remove-owner MyLibrary developer@email.com

現在の所有者のみが所有者を削除できます。podの最後の所有者は削除できません — 最初に新しい所有者を追加する必要があります。これにより、podが所有者なしになり放置されるのを防ぎます。

podの非推奨マーク付け

ライブラリがメンテナンスされなくなった場合、非推奨（deprecated）としてマークできます。これによりpodがレジストリから削除されることはありませんが、インストール時にユーザーに警告が表示されます。

pod trunk deprecate MyLibrary

オプションで、代替podを指定できます。

pod trunk deprecate MyLibrary --in-favor-of=NewLibrary

非推奨のpodをインストールすると、CocoaPodsはターミナルに警告を表示し、指定された代替への切り替えを推奨します。これは、既存のプロジェクトのビルドを壊さずにライブラリのサポートを終了する正しい方法です。

pod情報の表示

pod情報はpod trunk infoコマンドで利用できます。

pod trunk info MyLibrary

このコマンドは、すべてのpodバージョン、公開日、所有者リスト、ステータス（アクティブ/非推奨）を表示します。特定のバージョンの詳細を表示するには、pod spec cat MyLibrary 0.1.0を使用します。

エラーと解決策

Trunkを使用する際、開発者はよく典型的なエラーに遭遇します。最も一般的なものを見ていきましょう。

認証エラー

症状： [!] Authentication failed. You need to register a session first.
原因： セッショントークンがないか期限切れ。トークンには有効期限があります（デフォルトでは30日間アクティビティがない場合）。
解決策： pod trunk register your@email.com 'Your Name'を再実行します。CIを使用している場合は、COCOAPODS_TRUNK_TOKEN環境変数が最新かどうかを確認し、必要に応じて新しいトークンを生成します。

バージョン競合

症状： [!] You have already pushed version 0.1.0 for MyLibrary.
原因： 既存のバージョンを再公開しようとしています。Trunkはバージョンの上書きを許可しません。
解決策： セマンティックバージョニングに従ってpodspecのバージョンを上げます。podspecを間違えた場合は、修正を加えた次のバージョンを公開します。

Podspec検証エラー

症状： [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
原因： source_filesフィールドのソースファイルへのパスが正しくありません。
解決策： podspecのパスを確認し、すべてのエラーが解決されるまでローカルでpod lib lintを実行し、その後公開を再試行します。グロブパターンを使用します：Classes/**/*.{h,m}、Sources/MyLibrary/**/*.swift。

接続タイムアウト

症状： [!] Connection to trunk.cocoapods.org failed. Timeout.
原因： ネットワークの問題またはTrunkサーバーの一時的な利用不可。
解決策： サーバーの可用性を確認します：curl -I https://trunk.cocoapods.org。サーバーが応答する場合は、数分後にコマンドを再試行します。IPがブロックされている可能性があります — 別の接続またはVPNから試してください。

podへのアクセス権がない

症状： [!] You do not have permission to push to MyLibrary.
原因： あなたはpodの所有者ではありません。これは、誰かが既にその名前でpodを登録している場合に発生します。
解決策： 現在のpod所有者に連絡し（pod trunk info MyLibraryで確認）、pod trunk add-ownerを介して追加してもらうよう依頼します。pod名が既に使用されている場合は、代替名を検討します。