Podfile 用來描述一個或多個專案中,各 target 之間的依賴關係。若沒有特別指定,CocoaPods 會建立一個隱式的 target 鏈接到使用者專案的第一個 target,名稱為 default。
最精簡的 Podfile 可以只有一行:
pod 'AFNetworking', '~> 1.0'
也可以寫得完整一些:
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '6.0'
inhibit_all_warnings!
xcodeproj 'MyProject'
pod 'ObjectiveSugar', '~> 0.5'
target :test do
pod 'OCMock', '~> 2.0.1'
end
post_install do |installer|
installer.pods_project.targets.each do |target|
puts #{target.name}
end
end
這一段說明如何在 Podfile 中描述各 target 的依賴,主要用到三個關鍵字:pod 宣告指定依賴,podspec 提供建立 podspec 的簡化 API,target 則讓依賴只在指定 target 中生效。
宣告一個依賴,由 pod 名稱加上選用的版本號組成。
專案剛起步時通常直接用最新版,可以省略版本號:
pod 'SSZipArchive'
想鎖定版本時寫上具體版本即可:
pod 'Objection', '0.9'
版本號除了「指定」與「不指定」,還支援運算子做範圍比對:
>0.1 高於 0.1 的任何版本 >=0.1 0.1 及任何更高版本 <0.1 低於 0.1 的任何版本 <=0.1 0.1 及任何較低版本 ~>0.1.2 0.1.2 到 0.2(不含 0.2)之間的最新版本
其中 ~> 的行為值得多說一句:它以你指定版本號的最後一段為界線。上例等效於 >= 0.1.2 且 < 0.2.0,並會取範圍內最新的版本。這種寫法適合在「不想被破壞性改動影響」與「想拿到修補更新」之間取得平衡。
最後,可以用 :head 指定版本。這代表使用該 podspec 下最新的可用版本,但會強制拉取 HEAD 這種走在最前線的版本:
pod 'Objection', :head
風險自行承擔——spec 可能與你的專案不相容。
官方提醒:以下語法屬於過渡性質,未來可能變動且不另行通知。因為需求太熱烈,這個功能就先推出了,你可能需要為未來版本的 CocoaPods 調整 Podfile。無論如何,日後會提供清晰簡易的升級路徑。
依賴預設會被安裝到所有 target 的 build configuration。基於除錯或其他理由,可以讓它只在特定 configuration 生效:
pod 'PonyDebugger', :configurations => ['Release', 'App Store']
用名稱安裝一個 pod 時,會安裝該 podspec 中所有預設的 subspec。也可以只挑其中幾個:
pod 'QueryKit/Attribute'
pod 'QueryKit', :subspecs => ['Attribute', 'QuerySet']
想用自己開發中的本地 pod,可以用 path 選項:
pod 'AFNetworking', :path => '~/Documents/AFNetworking'
設定了這個選項,CocoaPods 會把該資料夾視為 pod 來源並直接引用其中的檔案,因此你在裡面的修改會被保留,不會被安裝流程覆蓋。這個資料夾可以來自你慣用的版控系統,甚至只是目前 repo 的一個 git submodule。
注意:pod 的 podspec 檔也必須放在這個資料夾內。
有時你想用開發中的最新版或某個二次修改版本,可以直接在 pod 宣告裡標明來源。
使用 master 分支:
pod 'AFNetworking', :git => 'https://github.com/gowalla/AFNetworking.git'
使用其他分支:
pod 'AFNetworking', :git => 'https://github.com/gowalla/AFNetworking.git', :branch => 'dev'
使用某個 tag:
pod 'AFNetworking', :git => 'https://github.com/gowalla/AFNetworking.git', :tag => '0.7.0'
或使用某次 commit:
pod 'AFNetworking', :git => 'https://github.com/gowalla/AFNetworking.git', :commit => '082f8319af'
這種寫法雖然能滿足 pod 內部透過其他 pod 宣告的依賴,但前提是 podspec 必須存在於 repo 根目錄。若根目錄沒有這個檔案,就得改用下面幾種方式之一。
如果某個 podspec 能從外部來源取得,甚至可以直接用 HTTP 拉:
pod 'JSONKit', :podspec => 'https://example.com/JSONKit.podspec'
使用某個 podspec 中宣告的依賴。若不帶參數,會採用 Podfile 根部的第一個 podspec。
注意:這只會包含來自 CocoaPods 基礎架構的資源,不含 podspec 自身攜帶的資源。
podspec podspec :name => 'QuickDialog' podspec :path => '/Documents/PrettyKit/PrettyKit.podspec'
在 target 區塊內定義依賴;若不想讓該 target 繼承外層的依賴,可加上 :exclusive => true。
Podfile 會建立一個名為 default 的全域 target,產生 libPod.a,並在未指定 link_with 時綁定使用者專案的第一個 target。
target :ZipApp do
pod 'SSZipArchive'
end
target :ZipApp do
pod 'SSZipArchive'
target :test, :exclusive => true do
pod 'JSONKit'
end
end
這些設定用來控制 CocoaPods 產生的 project。開頭的 platform 說明工作平台,xcodeproj 則指定要鏈接的專案。
指定靜態庫要為哪個平台編譯。若未自行指定,CocoaPods 會套用預設部署目標(iOS 4.3、OS X 10.6、tvOS 9.0、watchOS 2.0)。若部署目標要求 iOS 低於 4.3,armv6 架構會被加入 ARCHS。
platform :ios platform :ios, '7.0'
指定包含要鏈接 pod 庫之 target 的 Xcode 專案。若未明確指定,會沿用 target 父層設定的專案;若都沒有,則使用與 Podfile 同目錄的專案。也可以指定設定只在 release 或 debug 下生效,做法是搭配 :release / :debug。
xcodeproj 'MyProject'
target :test do
# 這個 Pods 庫鏈接到另一個專案中的 target
xcodeproj 'TestProject'
end
xcodeproj 'TestProject', 'Mac App Store' => :release, 'Test' => :debug
指定使用者專案中的哪些 target 要鏈接到 pod 庫。若未指定,預設鏈接第一個 target;因此只需鏈接第一個時,可以完全不寫。
link_with 'MyApp' link_with 'MyApp', 'MyOtherApp'
屏蔽 CocoaPods 庫中的所有編譯警告。這個特性也能在子 target 內定義;若只想屏蔽某個 pod 的警告:
pod 'SSZipArchive', :inhibit_warnings => true
改用 framework 取代靜態庫。這個特性可以透過定義子 target 來繼承。
指定包含所有 projects 的 Xcode workspace。若未明確指定,且 Podfile 所在目錄只有一個 project,則該 project 名稱會被用作 workspace 名稱。
workspace 'MyWorkspace'
指定後,會從所有已安裝 pod 的標頭檔產生一份 BridgeSupport 中介資料文件。MacRuby、Nu、JSCocoa 等腳本語言可以利用它取得橋接型別與函式資訊。
指定後,-fobjc-arc 旗標會被加入 OTHER_LD_FLAGS,用來解決編譯 non-ARC 專案時出現的 bug(見 issue #142)。這件事原本由 Xcode 4.3.2 的 libtool 自動處理,但 -fobjc-arc 後來不再被支援,因此必須明確指定。此方法在 CocoaPods 1.0 中可能會被棄用。
Podfile 會從所有 sources(repos)中檢索 specs。Sources 是全域的,不存在每個 target 定義裡。
指定 specs 的位置。順序是有意義的:CocoaPods 會採用 pod 第一次出現的 source 中的最高版本,後續 source 即使有更高版本也不予考慮。
另外,官方 source 是隱式需要的;一旦你指定了其他 source,就得把官方的也補上。
source 'https://github.com/artsy/Specs.git' source 'https://github.com/CocoaPods/Specs.git'
Podfile 提供了在安裝過程中被呼叫的鉤子。鉤子是全域的,不存在每個 target 定義裡。
指定安裝過程中要使用的插件,並可同時傳入選項。
plugin 'cocoapods-keys', :keyring => 'Eidolon' plugin 'slather'
讓你在 pods 下載完成、尚未安裝之前對它們做一些調整。唯一參數是 Pod::Installer。
pre_install do |installer|
# 在這裡做些 preprocessing
end
讓你在 Xcode project 寫入硬碟(或其他後續操作)之前做最後的修改。唯一參數同樣是 Pod::Installer。
post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['GCC_ENABLE_OBJC_GC'] = 'supported'
end
end
end
這個鉤子最常見的用途,就是統一調整所有 target 的編譯設定——例如全域關閉警告、切換 Swift 版本、或補上 linker flags。