Podfile 语法参考 v1.14.3

install!

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

第一个参数指示要使用的安装方法；后面的参数指示安装选项。

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

示例

指定自定义 CocoaPods 安装选项

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

支持的键

:clean

是否在安装期间清理 pod 的源

清理会移除 podspec 和项目支持的平台未使用的任何文件

此选项默认为 true。

:deduplicate_targets

是否对 pod 目标进行去重

目标去重为 pod 目标添加后缀，以防 pod 包含在具有不同要求的多个目标中。例如，名为“MyPod”的 pod 带有子规范“SubA”，该子规范包含在以下两个目标中

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

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

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

此选项默认为 true。

:lock_pod_sources

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

在安装期间锁定 pod 会带来性能损失。如果这会显著影响你项目的 pod install 的持续时间，你可以尝试将其设置为 false

此选项默认为 true。

:warn_for_multiple_pod_sources

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

此选项默认为 true。

:warn_for_unused_master_specs_repo

如果项目未明确指定基于 git 的主规范存储库，并且可以改用默认的 CDN，是否发出警告。

此选项默认为 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 目标生成一个项目。此选项不会创建 1 个 Pods.xcodeproj，而是会为每个 Pod 目标生成一个项目，这些项目将嵌套在 Pods.xcodeproj 下。

此选项默认为 false。

:incremental_installation

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

此选项默认为 false。

:skip_pods_project_generation

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

此选项默认为 false。

:parallel_pod_downloads

是否在开始安装过程之前并行下载 Pod

此选项默认为 false。

:parallel_pod_download_thread_pool_size

并行下载 Pod 时要使用的线程池大小。仅在 parallel_pod_downloads 为 true 时生效。

默认值：40

此选项默认为 40。

ensure_bundler!

当使用全局 Gemset 运行 CocoaPods 时，会发出警告。如果捆绑器版本与所需版本不匹配，可以提供语义版本以发出警告。

参数

示例

ensure_bundler!

ensure_bundler! '~> 2.0.0'

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 版本 0 和高达 1 的版本，不包括 1。
• ~> 0.1.3-beta.0 0.1.3 的 Beta 版和发布版，高达 0.2 的发布版，不包括 0.2。用破折号 (-) 分隔的组件将不被考虑用于版本要求。

可以指定版本要求列表以实现更精细的控制。

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

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

构建配置

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

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://cdn.cocoapods.org/'

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

子规范

通过其名称安装 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 声明中指定它。

要使用存储库的 master 分支

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 文件，则您将必须使用下面部分中概述的方法之一。

对于没有 podspec 的库，从规范存储库外部的 podspec。

如果 podspec 可从库存储库外部的另一个来源获得。例如，考虑通过 HTTP 可用的 podspec

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

podspec

仅使用给定 podspec 文件中定义的 Pod 的依赖项。如果没有传递参数，则使用 Podfile 根目录中的第一个 podspec。它旨在供库项目使用。注意：这不包括从 podspec 派生的源，仅包括 CocoaPods 基础设施。

参数

示例

podspec

podspec :name => 'QuickDialog'

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

target

定义一个 CocoaPods 目标和作用域，在给定的块中定义依赖项。一个目标应该对应一个 Xcode 目标。默认情况下，目标包括在块外部定义的依赖项，除非指示不inherit!它们。

参数

示例

定义一个目标

target 'ZipApp' do
  pod 'SSZipArchive'
end

定义一个测试目标，从其父级访问 SSZipArchive pod

target 'ZipApp' do
  pod 'SSZipArchive'

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

定义一个目标通过其父级目标将 Pods 应用于多个目标

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 环境变量。一个目标可能包含多个脚本阶段，它们将按声明的顺序添加。如果之前已添加删除一个脚本阶段，将有效地将其从目标中移除。

参数

示例

script_phase :name => 'HelloWorldScript', :script => 'echo "Hello World"'

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

abstract_target

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

参数

示例

定义一个抽象目标

abstract_target 'Networking' do
  pod 'AlamoFire'

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

定义一个 abstract_target，将 Pods 包装到多个目标

# 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!

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

参数

示例

仅继承搜索路径

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

platform

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

如果未指定，CocoaPods 会提供默认部署目标。当前的默认值为 iOS 的4.3、OS X 的10.6、tvOS 的9.0、visionOS 的1.0和 watchOS 的2.0。

如果部署目标需要（iOS < 4.3），armv6 架构将被添加到 ARCHS。

参数

示例

指定平台

platform :ios, '4.0'
platform :ios

project

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

如果没有任何目标定义指定明确的项目，并且 Podfile 所在目录中只有一个项目，则将使用该项目。

还可以指定自定义构建配置的构建设置应仿照发行版还是调试版预设。为此，您需要指定一个哈希，其中每个构建配置的名称都与 :release 或 :debug 关联。

参数

示例

指定用户项目

# 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。使用框架时，你还可以指定 :linkage 样式，可以是 :static 或 :dynamic。

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

参数

示例

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

target 'MyApp' do
  use_frameworks! :linkage => :dynamic
  pod 'AFNetworking', '~> 1.0'
end

target 'ZipApp' do
  use_frameworks! :linkage => :static
  pod 'SSZipArchive'
end

supports_swift_versions

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

注意如果指定了这些要求，则从父级继承这些要求，如果在根级别未指定任何要求，则认为支持所有版本。

参数

示例

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 所在目录中仅存在一个项目，则该项目的名称将用作工作区的名称。

参数

示例

指定工作区

workspace 'MyWorkspace'

generate_bridge_support!

指定应从所有已安装 Pod 的头文件中生成 BridgeSupport 元数据文档。

这是针对诸如 MacRuby、Nu 和 JSCocoa 等脚本语言的，它们使用它来桥接类型、函数等。

set_arc_compatibility_flag!

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

这是作为非 ARC 项目的编译器错误的解决方法（请参见 #142）。最初这是自动完成的，但 Xcode 4.3.2 中的 libtool 似乎不再支持 -fobjc-arc 标志。因此，现在必须使用此方法明确启用它。

CocoaPods 1.0 中可能会删除对此方法的支持。

source

指定规范的位置

使用此方法指定来源。来源的顺序很重要。CocoaPods 将使用包含 Pod 的第一个来源的 Pod 的最高版本（无论其他来源是否具有更高版本）。

官方 CocoaPods 来源是隐式的。一旦你指定了另一个来源，则需要包含它。

参数

示例

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

source 'https://github.com/artsy/Specs.git'
source 'https://cdn.cocoapods.org/'

plugin

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

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

参数

示例

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

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

pre_install

此钩子允许你在下载 Pod 之后但在安装 Pod 之前对 Pod 进行任何更改。

它接收 [Pod::Installer] 作为其唯一参数。

示例

在 Podfile 中定义预安装钩子。

pre_install do |installer|
  # Do something fancy!
end

pre_integrate

此钩子允许你在将项目写入磁盘之前进行更改。

它接收 [Pod::Installer] 作为其唯一参数。

示例

在集成之前自定义依赖项

pre_integrate do |installer|
  # perform some changes on dependencies
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

post_integrate

此钩子允许你在将项目写入磁盘之后进行更改。

它接收 [Pod::Installer] 作为其唯一参数。

示例

自定义所有目标的构建设置

post_integrate do |installer|
  # some change after project write to disk
end