Podfile语法中文参考文档 – CocoaPods教程

上一章CocoaPods教程请查看：创建一个CocoaPods

Podfile

Podfile是描述一个或多个Xcode项目的target的依赖性的规范描述文件。

Podfile文件可以很简单:

target 'MyApp'
pod 'AFNetworking', '~> 1.0'

一个更复杂的Podfile的例子是

platform :ios, '9.0'
inhibit_all_warnings!

target 'MyApp' do
  pod 'ObjectiveSugar', '~> 0.5'

  target 'MyAppTests' do
    inherit! :search_paths
    pod 'OCMock', '~> 2.0.1'
  end
end

post_install do |installer|
  installer.pods_project.targets.each do |target|
    puts "#{target.name}"
  end
end

根选项

应用于整个Podfile的配置。

install!声明安装过程中使用的安装方法和选项。

install!

指定CocoaPods安装这个Podfile时使用的安装方法和选项。

第一个参数表示使用的安装方法；接下来的参数指示安装选项。

目前唯一被接受的安装方法是“cocoapods”，因此你将始终对第一个参数使用此值；但是在未来的版本中可能会有更多的安装方法。

例子:

指定自定义CocoaPods安装选项

install! 'cocoapods',
         :deterministic_uuids => false,
         :integrate_targets => false

支持的Key

:clean

安装过程中是否清理pod的来源

清理将删除pod没有使用的所有文件，这些文件由podspec和项目支持的平台指定

该选项默认为true。

:deduplicate_targets

是否去复制pod的target

当一个pod包含在多个具有不同需求的target中时，target重复数据删除会向pod target添加后缀。例如，一个名为“MyPod”的pod有一个subspec“SubA”，包含在两个target中，如下所示:

target 'MyTargetA' do
  pod 'MyPod/SubA'
end

target 'MyTargetB' do
  pod 'MyPod'
end

会产生两个Pod目标：MyPod和MyPod- suba

该选项默认为true。

:deterministic_uuids

在创建Pods项目时是否生成确定性uuid

该选项默认为true。

:integrate_targets

是否将安装的pods集成到用户项目中

如果设置为false, Pods将被下载并安装到Pods/目录中，但是它们不会集成到你的项目中。

该选项默认为true。

:lock_pod_sources

是否锁定pods的源文件。当试图修改文件内容时，Xcode将提示解锁文件

在安装期间锁定吊舱会导致性能损失。如果这对项目的pod安装持续时间有显著影响，可以尝试将其设置为false

该选项默认为true。

:warn_for_multiple_pod_sources

当多个源包含具有相同名称和版本的Pod时，是否发出警告

该选项默认为true。

:share_schemes_for_development_pods

是否共享开发pod的Xcode方案。

开发pod的方案是自动创建的，但默认情况下不共享。

该选项默认为false。

:disable_input_output_paths

是否禁用CocoaPods脚本阶段的输入和输出路径(复制框架和复制资源)

该选项默认为false。

:preserve_pod_file_structure

是否保留所有pod的文件结构，包括外部pod源。

默认情况下，Pod源的文件结构仅为开发Pod保留。设置:preserve_pod_file_structure为true将始终保存文件结构。

该选项默认为false。

:generate_multiple_pod_projects

是否为每个pod目标生成一个项目，而不是创建一个Pods.xcodeproj，此选项将为嵌套在Pods.xcodeproj下的每个pod目标生成一个项目。

该选项默认为false。

:incremental_installation

是否仅启用自上次安装以来已更改的重新生成目标及其关联项目。

该选项默认为false。

:skip_pods_project_generation

是否跳过生成Pods.xcodeproj，只执行依赖项解析和下载。

该选项默认为false。

Podfile依赖

Podfile指定每个用户target的依赖项。

• pod是声明特定依赖项的方法。
• podspec为创建podspec提供了一个简单的API。
• target是你在Xcode项目中如何将依赖项限定为特定target的范围。

pod

指定项目的依赖项。

依赖项需求由Pod的名称和版本需求列表(可选)定义。

在开始一个项目时，你可能希望使用最新版本的Pod。如果是这种情况，只需忽略版本需求，如下是一个例子。

pod 'SSZipArchive'

在项目的后期，你可能希望使用Pod的特定版本，在这种情况下，你可以指定版本号。

pod 'Objection', '0.9'

除了没有版本，或者一个特定的版本，也可以使用操作符:

• = 0.1，版本0.1。
• > 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相结合，并且总是匹配与你的需求相匹配的最新已知版本。
• ~ > 0.1.3-beta.0，Beta版和release发行版本为0.1.3，发行版本为0.2(不包括0.2)。用破折号(-)分隔的组件将不考虑版本要求。

可以为更细粒度的控制指定版本需求列表。

有关版本控制策略的更多信息，请参见:

• 语义版本控制
• RubyGems版本管理策略

构建配置

默认情况下，依赖项安装在target的所有构建配置中。出于调试目的或其他原因，只能在构建配置列表中启用它们。

pod 'PonyDebugger', :configurations => ['Debug', 'Beta']

或者，你可以指定将其包含在单个构建配置中。

pod 'PonyDebugger', :configuration => 'Debug'

请注意，所有配置中都包含传递依赖项，如果不希望这样，还必须手动为它们指定生成配置。

模块头

如果你想使用模块化的头，每个Pod你可以使用以下语法:

pod 'SSZipArchive', :modular_headers => true

另外，当你使用use_modular_headers!属性时，你可以使用以下命令从模块头中排除特定的Pod:

pod 'SSZipArchive', :modular_headers => false

源

默认情况下，在全局级别指定的源按照指定依赖项匹配的顺序进行搜索。这种行为可以通过指定依赖项的来源来改变特定的依赖项:

pod 'PonyDebugger', :source => 'https://github.com/CocoaPods/Specs.git'

在这种情况下，将只搜索指定的源，以查找依赖项和任何被忽略的全局源。

Subspecs

当通过它的名字安装Pod时，它将安装podspec中定义的所有默认的子规范。

你可以安装一个特定的子规格使用以下:

pod 'QueryKit/Attribute'

你可以指定一个要安装的子规格集合如下:

pod 'QueryKit', :subspecs => ['Attribute', 'QuerySet']

测试规格

可以通过:testspecs选项选择性地包括测试规格。默认情况下，不包括Pod的测试规范。

你可以指定一个测试规范名称列表来安装，使用如下方法:

pod 'AFNetworking', :testspecs => ['UnitTests', 'SomeOtherTests']

提供给:testspecs的值对应于提供给Podspec中的test_spec DSL属性的名称。

依赖关系也可以从外部来源获得。

使用本地路径中的文件

如果你想使用与它的客户端项目一起开发一个Pod，你可以使用path选项。

pod 'AFNetworking', :path => '~/Documents/AFNetworking'

使用此选项CocoaPods将假定给定文件夹是Pod的根文件夹，并将从那里直接链接到Pods项目中的文件。这意味着你的编辑将持续到CocoaPods安装。

被引用的文件夹可以是你最喜欢的SCM的签出，甚至是当前存储库的git子模块。

注意，Pod文件的podspec应该在文件夹中。

来自库存储库根中的podspec。

有时你可能会想要使用边缘版本的pod，或者一个特定的修改。如果是这种情况，你可以使用pod声明来指定。

要使用储存库的主分支:

pod 'AFNetworking', :git => 'https://github.com/gowalla/AFNetworking.git'

要使用存储库的不同分支:

pod 'AFNetworking', :git => 'https://github.com/gowalla/AFNetworking.git', :branch => 'dev'

使用存储库的标记

pod 'AFNetworking', :git => 'https://github.com/gowalla/AFNetworking.git', :tag => '0.7.0'

或者指定一个提交

pod 'AFNetworking', :git => 'https://github.com/gowalla/AFNetworking.git', :commit => '082f8319af'

但是，需要注意的是，这意味着该版本必须满足其他Pod对Pod的任何其他依赖关系。

podspec文件应该在存储库的根目录中，如果这个库的存储库中还没有podspec文件，那么你必须使用下面小节中列出的方法之一。

来自spec库之外的podspec，用于没有podspec的库

如果podspec可以从库库外的其他来源获得。例如，考虑一个可以通过HTTP访问的podspec:

pod 'JSONKit', :podspec => 'https://example.com/JSONKit.podspec'

podspec

只使用给定的podspec文件中定义的Pod的依赖项。如果没有传递任何参数，则使用Podfile根目录中的第一个podspec。它将用于库的项目。注意:这并不包括来自podspec的源代码，只包括CocoaPods基础结构。

参数

选项 Hash{符号= >字符串}

加载{Specification}的路径。如果没有提供，将使用Podfile目录中的第一个podspec。

例子:

podspec
podspec :name => 'QuickDialog'
podspec :path => '/Documents/PrettyKit/PrettyKit.podspec'

target

定义给定块中定义的CocoaPods target和范围依赖项。target应该与Xcode target相对应。默认情况下，target包含定义在块外部的依赖项，除非指示不要继承inherit!他们。

参数

名称 Symbol, String

目标的名称。

例子:

定义一个target

target 'ZipApp' do
  pod 'SSZipArchive'
end

定义从其父target访问SSZipArchive pod的测试target

target 'ZipApp' do
  pod 'SSZipArchive'

  target 'ZipAppTests' do
    inherit! :search_paths
    pod 'Nimble'
  end
end

定义一个target可以通过它的父target将Pods应用到多个target

target 'ShowsApp' do
  pod 'ShowsKit'

  # Has its own copy of ShowsKit + ShowTVAuth
  target 'ShowsTV' do
    pod 'ShowTVAuth'
  end

  # Has its own copy of Specta + Expecta
  # and has access to ShowsKit via the app
  # that the test target is bundled into

  target 'ShowsTests' do
    inherit! :search_paths
    pod 'Specta'
    pod 'Expecta'
  end
end

script_phase

添加与此目标集成的脚本阶段。脚本阶段可用于执行任意脚本，该脚本可在执行期间使用所有Xcode环境变量。目标可以包括多个脚本阶段，它们将按照声明的顺序被添加。如果之前已经添加了脚本阶段，那么删除脚本阶段将有效地将其从目标中删除。

参数

选项 Hash

此脚本阶段的选项。

例子:

script_phase :name => 'HelloWorldScript', :script => 'echo "Hello World"'
script_phase :name => 'HelloWorldScript', :script => 'puts "Hello World"', :shell_path => '/usr/bin/ruby'

abstract_target

定义一个新的抽象目标，可用于方便的目标依赖项继承。

参数

name Symbol,字符串

目标的名称。

例子:

定义抽象目标

abstract_target 'Networking' do
  pod 'AlamoFire'

  target 'Networking App 1'
  target 'Networking App 2'
end

定义一个abstract_target包装pod到多个目标

# Note: There are no targets called "Shows" in any of this workspace's Xcode projects
abstract_target 'Shows' do
  pod 'ShowsKit'

  # The target ShowsiOS has its own copy of ShowsKit (inherited) + ShowWebAuth (added here)
  target 'ShowsiOS' do
    pod 'ShowWebAuth'
  end

  # The target ShowsTV has its own copy of ShowsKit (inherited) + ShowTVAuth (added here)
  target 'ShowsTV' do
    pod 'ShowTVAuth'
  end

  # Our tests target has its own copy of
  # our testing frameworks, and has access
  # to ShowsKit as well because it is
  # a child of the abstract target 'Shows'

  target 'ShowsTests' do
    inherit! :search_paths
    pod 'Specta'
    pod 'Expecta'
  end
end

abstract!

表示当前目标是抽象的，因此不会直接链接到Xcode目标。

inherit!

设置当前目标的继承模式。

参数

继承Symbol

要设置的继承模式。

可用模式:+:complete 目标继承父模式的所有行为。目标不会从父类继承任何行为。目标只继承父类的搜索路径。

例子:

只继承搜索路径

target 'App' do
  target 'AppTests' do
    inherit! :search_paths
  end
end

target配置

这些设置用于控制CocoaPods生成的项目。

首先简单地说明你在哪个platform平台上工作。xcodeproj允许你明确声明要链接到哪个项目。

platform

指定应为其构建静态库的平台。

如果未指定CocoaPods，则提供默认部署目标。 当前的默认值对于iOS是4.3，对于OS X是10.6，对于tvOS是9.0，对于watchOS是2.0。

如果部署目标需要它（iOS <4.3），则将armv6体系结构添加到ARCHS。

参数

名称 Symbol

平台的名称，对于OS X可以是:osx，对于iOS可以是:ios，对于tvOS是:tvos，或者对于watchOS是:watchos。

target String，版本

可选部署。 如果未提供，则将根据平台名称分配默认值。

例子：

指定平台

platform :ios, '4.0'
platform :ios

project

指定包含Pods库应该链接的目标的Xcode项目。

如果没有目标定义指定一个显式项目，并且与Podfile在同一目录中只有一个项目，那么将使用该项目。

还可以指定你的自定义构建配置的构建设置是在版本发布之后建模还是在调试预置之后建模。为此，你需要指定一个散列，其中每个构建配置的名称关联到:release或:debug。

参数

path String

要链接的项目的路径

build_configurationsHash{字符串= >符号}

一个散列，其中键是Xcode项目中构建配置的名称，值是一些符号，这些符号指定配置应该基于:debug还是:release配置。如果在您的项目中没有为配置指定显式的映射，它将默认为:release。

例子:

指定用户项目

# This Target can be found in a Xcode project called `FastGPS`
target 'MyGPSApp' do
  project 'FastGPS'
  ...
end

# Same Podfile, multiple Xcodeprojects
target 'MyNotesApp' do
  project 'FastNotes'
  ...
end

使用自定义构建配置

project 'TestProject', 'Mac App Store' => :release, 'Test' => :debug

xcodeproj

xcodeproj在1.0中被弃用，并被重命名为project。对于1.0之前的版本使用xcodeproj。

link_with

link_with在1.0中被弃用，取而代之的是abstract_target和目标继承。

inhibit_all_warnings!

禁止来自CocoaPods库的所有警告。

此属性由子目标定义继承。

如果你想禁止每个Pod的警告，你可以使用以下语法:

pod 'SSZipArchive', :inhibit_warnings => true

另外，当你使用inhibit_all_warnings!属性，你可以使用以下方法来排除特定的Pod:

pod 'SSZipArchive', :inhibit_warnings => false

use_modular_headers!

对所有CocoaPods静态库使用模块化头文件。

此属性由子目标定义继承。

如果你想使用模块化的头每个Pod你可以使用以下语法:

pod 'SSZipArchive', :modular_headers => true

另外，当你使用use_modular_headers!属性，可以使用以下命令从模块头中排除特定的Pod

pod 'SSZipArchive', :modular_headers => false

use_frameworks!

为Pods使用框架而不是静态库。

此属性由子目标定义继承。

supports_swift_versions

指定目标定义支持的Swift版本要求。

注意，这些需求是从父级继承的，如果指定了这些需求，并且在根级没有指定任何需求，那么所有版本都被认为是受支持的。

参数

需求 String，版本，数组，数组

此目标支持的需求集。

例子:

target 'MyApp' do
  supports_swift_versions '>= 3.0', '< 4.0'
  pod 'AFNetworking', '~> 1.0'
end


supports_swift_versions '>= 3.0', '< 4.0'

target 'MyApp' do
  pod 'AFNetworking', '~> 1.0'
end

target 'ZipApp' do
  pod 'SSZipArchive'
end

工作空间

该组列出配置工作区和设置全局设置的选项。

workspace

指定应该包含所有项目的Xcode工作区。

如果没有指定显式的Xcode工作空间，并且只有一个项目存在于与Podfile相同的目录中，那么该项目的名称将用作工作空间的名称。

参数

path String

工作区的路径。

例子:

指定一个工作区

workspace 'MyWorkspace'

generate_bridge_support!

指定一个BridgeSupport元数据文档应该从所有安装的pod的标题生成。

这适用于脚本语言，如MacRuby、Nu和JSCocoa，它们使用它来桥接类型、函数等。

set_arc_compatibility_flag!

指定-fobjc-arc标志应该添加到OTHER_LD_FLAGS。

对于非arc项目的编译器缺陷，这是一种变通方法(参见#142)。这最初是自动完成的，但从Xcode 4.3.2开始的libtool似乎不再支持-fobjc-arc标志。因此，现在必须使用此方法显式地启用它。

CocoaPods 1.0中可能会取消对该方法的支持。

源

Podfile从给定的源(存储库)列表中检索规范。

源是全局的，它们不是按目标定义存储的。

source

指定规格的位置

使用此方法指定源。资料来源的顺序是相关的。CocoaPods将使用第一个来源的最高版本的Pod，其中包括Pod(不管其他来源是否有更高的版本)。

官方的CocoaPods来源是含蓄的。一旦指定了另一个源，就需要包含它。

参数

source String

规范存储库的URL。

例子:

指定首先使用Artsy存储库，然后使用CocoaPods主存储库

source 'https://github.com/artsy/Specs.git'
source 'https://github.com/CocoaPods/Specs.git'

Hook钩子

Podfile提供了将在安装过程中调用的钩子。

钩子是全局的，不是按目标定义存储的。

plugin

指定安装期间应该使用的插件。

使用此方法指定应在安装期间使用的插件，以及在调用插件时应传递给插件的选项。

参数

名称 String

插件的名称。

options Hash

在调用插件的钩子时应该传递给插件的可选选项。

例子:

指定使用“slather”和“cocoapods-keys”插件。

plugin 'cocoapods-keys', :keyring => 'Eidolon'
plugin 'slather'

pre_install

这个钩子允许你在下载了pod并安装它们之前对它们做任何修改。

它接收Pod::Installer作为惟一的参数。

例子:

在Podfile中定义预安装钩子。

pre_install do |installer|
  # Do something fancy!
end

post_install

这个钩子允许你在将生成的Xcode项目写入磁盘之前对其进行最后的更改，或者执行你可能希望执行的任何其他任务。

它接收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