Podspec语法参考(翻译)
目录
规范
规范描述了Pod库的版本。它包括从何处获取源、使用哪些文件、应用的构建设置以及其他常规元数据(例如:名称、版本和说明)等详细信息。
可以通过pod spec create
命令生成存根规范文件(podspec文件)
。
DSL规范提供了极大的灵活性和动态性。此外,DSL采用了按约定编程。因此他可以非常的简单:
1 | Pod::Spec.new do |spec| |
或者更详细一些:
1 | Pod::Spec.new do |spec| |
约定优于配置(convention over configuration),也称为按约定编程,是一种软件设计范式,旨在减少软件开发人脸需要做决定的数量,获得简单的好处,而又不失灵活性。
根规范
“根”规范存储有关库的特定版本的信息。
此组中的属性只能写入“根”规范,而不能写入“子规范”。
此组中列出的属性是podspec所需的唯一属性。
提供其他组的属性来改进podspec,并遵循一种约定优于配置的方法。根规范可以通过“子规范”直接描述这些属性。
name
==必须设置!==
pod的名字。
例如:
1 | spec.name = 'AFNetworking' |
version
==必须设置!==
pod的版本。CocoaPods遵循语义版本控制。
例如:
1 | spec.version = '0.0.1' |
swift_versions
规范支持的Swift版本。“4”的版本将被CocoaPods视为“4.0”,而不是“4.1”或“4.2”。
请注意,Swift编译器主要接受高级版本,有时也支持低级版本。虽然CocoaPods允许指定低级版本或修补程序版本,但Swift编译器可能不会完全遵循它。
例如:
1 | spec.swift_versions = ['3.0'] |
1 | spec.swift_versions = ['3.0', '4.0', '4.2'] |
1 | spec.swift_version = '3.0' |
1 | spec.swift_version = '3.0', '4.0' |
cocoapods_version
规范支持的CocoaPods版本。
例如:
1 | spec.cocoapods_version = '>= 0.36' |
authors
==必须设置!==
库维护人员的姓名和电子邮件地址,而不是Podspec维护人员的姓名和电子邮件地址。
1 | spec.author = 'Darth Vader' |
1 | spec.authors = 'Darth Vader', 'Wookiee' |
1 | spec.authors = { 'Darth Vader' => 'darthvader@darkside.com', |
social_media_url
pod的社交媒体联系人的URL,CocoaPods web 服务可以使用这个。
例如,如果URL是相对于Twitter的,@CocoaPodsFeed通知将包括Twitter句柄(缩短描述)。这并不一定是一个Twitter URL,但是只有那些包含在Twitter @CocoaPodsFeed通知中。
例如:
1 | spec.social_media_url = 'https://twitter.com/cocoapods' |
1 | spec.social_media_url = 'https://groups.google.com/forum/#!forum/cocoapods' |
license
==必须设置!==
pod的许可证。
除非源包含名为LICENSE.*或LICENSE.*的文件,否则必须指定许可文件的路径或许可类型常用的通知的整数文本。如果指定了许可证文件,则它必须没有文件扩展名,或者是txt、md或markdown之一。
CocoaPods使用此信息生成确认文件(markdown和plit),这些文件可用于最终应用程序的确认部分。
例如:
1 | spec.license = 'MIT' |
1 | spec.license = { :type => 'MIT', :file => 'MIT-LICENSE.txt' } |
1 | spec.license = { :type => 'MIT', :text => <<-LICENSE |
支持keys:
1 | :type |
homepage
==必须设置!==
pod主页的URL。
例如:
1 | spec.homepage = 'http://www.example.com' |
source
==必须设置!==
可以从中检索库的位置。
例如:
指定带有标签(tag)的git源。这就是大多数OSS podspec的工作原理。
1 | spec.source = { :git => 'https://github.com/AFNetworking/AFNetworking.git', |
使用前缀为“V”和子模块的标签(tag)。
1 | spec.source = { :git => 'https://github.com/typhoon-framework/Typhoon.git', |
使用带标签(tag)的Subversion.
1 | spec.source = { :svn => 'http://svn.code.sf.net/p/polyclipping/code', :tag => '4.8.8' } |
使用与规范的语义版本字符串具有相同版本的Mercurial。
1 | spec.source = { :hg => 'https://bitbucket.org/dcutting/hyperbek', :revision => "#{s.version}" } |
使用HTTP下载压缩文件的代码。它支持zip、tgz、bz2、txz和tar。
1 | spec.source = { :http => 'http://dev.wechatapp.com/download/sdk/WeChat_SDK_iOS_en.zip' } |
使用HTTP下载文件,使用哈希验证下载。它支持sha1和sha256。
1 | spec.source = { :http => 'http://dev.wechatapp.com/download/sdk/WeChat_SDK_iOS_en.zip', |
支持Keys:
1 | :git => :tag, :branch, :commit, :submodules |
summary
==必须设置!==
对pod的简短描述(最多140个字符)。
摘要应该简短,但内容丰富。它代表pod的标签,无需指定它是一个库(虽然它是)。
该摘要首字母应大写并包含正确的标点符号。
例如:
1 | spec.summary = 'Computes the meaning of life.' |
description
对Pod的描述比摘要更详细。
例如:
1 | spec.description = <<-DESC |
screenshots
显示pod图片的url列表。面向用户界面的库。CocoaPods建议使用gif
格式。
例子:
1 | spec.screenshot = 'http://dl.dropbox.com/u/378729/MBProgressHUD/1.png' |
1 | spec.screenshots = [ 'http://dl.dropbox.com/u/378729/MBProgressHUD/1.png', |
documentation_url
CocaoPods web properties 将提供pod文档的可选URL。将其留空将默认为库的cocoadocs生成的URL。
例子:
1 | spec.documentation_url = 'http://www.example.com/docs.html' |
prepare_command
下载Pod后将执行bash脚本。此命令可用于创建、删除和修改下载的任何文件,并将在收集规范的其他文件属性的任何路径之前运行。
此命令在清理Pod和创建Pod项目之前运行。工作目录是Pod的根目录。
如果pod安装了:path
选项,则不会执行此命令。
例如:
1 | spec.prepare_command = 'ruby build_files.rb' |
1 | spec.prepare_command = <<-CMD |
static_framework
代表,如果使用use_frameworks!
指定时,pod应包含静态库框架。
例子:
1 | spec.static_framework = true |
deprecated
是否已弃用该库。
例子:
1 | spec.deprecated = true |
deprecated_in_favor_of
不赞成使用的Pod的名称。
例子:
1 | spec.deprecated_in_favor_of = 'NewMoreAwesomePod' |
平台
规范应指明支持库的平台和相应的部署目标。
如果未在子空间中定义,则此组的属性将继承父对象的值。
platform
pod支持的平台。不设置表示所有平台都支持。当支持多个平台时,您应该使用下面的部署目标。
例如:
1 | spec.platform = :osx, '10.8' |
1 | spec.platform = :ios |
1 | spec.platform = :osx |
deployment_target
平台支持最小版本。
与platform属性相反,deployment_target属性允许指定支持此pod的多个平台-为每个平台指定不同的部署目标。
例如:
1 | spec.ios.deployment_target = '6.0' |
1 | spec.osx.deployment_target = '10.8' |
构建设置
在这个组中列出了与构建环境的配置相关的属性,这些属性应该用于构建库。
如果没有在subspec中定义,这个组的属性将继承父元素的值。
dependency
对其pod或“sub-specification’”的依赖
依赖项可以指定版本。推荐使用版本指示器~>
,因为它提供了对版本的良好控制,而没有太多限制。例如,~>1.0.1
相当于>=1.0.1
且<1.1
。类似地,~>1.0
将匹配1.0
、1.0.1
和1.1
,但不会升级到2.0。
具有过度限制依赖关系的pod限制了它们与其他pod的兼容性。
例如:
1 | spec.dependency 'AFNetworking', '~> 1.0' |
1 | spec.dependency 'AFNetworking', '~> 1.0', :configurations => ['Debug'] |
1 | spec.dependency 'AFNetworking', '~> 1.0', :configurations => :debug |
1 | spec.dependency 'RestKit/CoreData', '~> 0.20.0' |
1 | spec.ios.dependency 'MBProgressHUD', '~> 0.5' |
info_plist
添加生成的info.plist
这些值将与CocoaPods生成的默认值合并,覆盖所有重复项。
对于库规范,这些值将合并到生成的信息列表对于使用框架集成的库。它对静态库没有影响。
不支持子服务器(应用程序和测试规范除外)。
对于应用程序规范,这些值将合并到应用程序主机的信息列表(Info.plist)
.
对于测试规范,这些值将合并到测试包的信息列表(Info.plist)
.
例如:
1 | spec.info_plist = { |
requires_arc
多平台
requires_arc
允许您指定哪个源_文件使用arc。这可以是支持ARC的文件,如果是true,表示所有源文件都使用ARC。
不使用ARC的文件将具有-fno-objc-arc
编译器标志。
此属性的默认值为true。
默认为:
1 | spec.requires_arc = true |
例如:
1 | spec.requires_arc = false |
1 | spec.requires_arc = 'Classes/Arc' |
1 | spec.requires_arc = ['Classes/*ARC.m', 'Classes/ARC.mm'] |
frameworks
多平台
用户目标需要链接的系统框架列表。
例如:
1 | spec.ios.framework = 'CFNetwork' |
1 | spec.frameworks = 'QuartzCore', 'CoreData' |
weak_frameworks
多平台
用户目标需要弱链接的框架列表。
例如:
1 | spec.weak_framework = 'Twitter' |
1 | spec.weak_frameworks = 'Twitter', 'SafariServices' |
libraries
多平台
用户的目标(应用程序)需要链接的系统库列表。
例如:
1 | spec.ios.library = 'xml2' |
1 | spec.libraries = 'xml2', 'z' |
compiler_flags
多平台
应传递给编译器的标志列表。
例如:
1 | spec.compiler_flags = '-DOS_OBJECT_USE_OBJC=0', '-Wno-format' |
pod_target_xcconfig
多平台
要添加到最终私有pod目标xcconfig文件的任何标志。
例如:
1 | spec.pod_target_xcconfig = { 'OTHER_LDFLAGS' => '-lObjC' } |
user_target_xcconfig
多平台
指定要添加到最终聚合目标xcconfig文件的标志,该文件将传播到非重写并将生成设置继承到集成用户目标。
不建议使用此属性,因为pod不应污染用户项目的生成设置,这可能会导致冲突。
将合并采用多个值的生成设置的多个定义。如果自定义生成设置和生成设置的定义冲突且只接受一个值,则会警告用户。
如果在用户目标中导入pod时需要使用clang编译器标志或预编译器宏定义,则通常会将它们放在此处。注意,这不仅会影响pod的公共接口的编译器视图,还会影响pod旁边的所有其他集成pod。您应该总是更喜欢pod_target_xcconfig
,它可以包含相同的设置,但只在编译pod目标时影响工具链。
例如:
1 | spec.user_target_xcconfig = { 'MY_SUBSPEC' => 'YES' } |
prefix_header_contents
多平台
要注入到pod项目前缀头中的任何内容。
不建议使用此属性,因为Pods不应该污染其他库或用户项目的前缀头。
例如:
1 | spec.prefix_header_contents = '#import <UIKit/UIKit.h>' |
1 | spec.prefix_header_contents = '#import <UIKit/UIKit.h>', '#import <Foundation/Foundation.h>' |
prefix_header_file
多平台
要注入pod项目前缀头的前缀头文件的路径。false表示不应生成默认CocoaPods前缀头。true是默认值,指示应生成默认CocoaPods前缀头。
不建议使用文件路径选项,因为Pods不应污染其他库或用户项目的前缀头。
例如:
1 | spec.prefix_header_file = 'iphone/include/prefix.pch' |
1 | spec.prefix_header_file = false |
module_name
将为此规范而不是默认规范生成的framework/clang模块使用的名称(如果设置了header_dir,则为规范名称)。
例如:
1 | spec.module_name = 'Three20' |
header_dir
多平台
存储头文件以使其不中断的目录包括。
例如:
1 | spec.header_dir = 'Three20Core' |
header_mappings_dir
多平台
用于保存头文件的文件夹结构的目录。如果没有提供头文件是扁平的。
例如:
1 | spec.header_mappings_dir = 'src/include' |
script_phases
多平台
此属性允许定义脚本阶段,作为Pod编译的一部分执行。与prepare命令不同,脚本阶段作为xcodebuild的一部分执行,它们还可以利用编译期间设置的所有环境变量。
pod可以提供多个脚本阶段来执行,它们将按照声明的顺序添加,并在考虑了它们的执行位置设置之后添加。
注意:为了提供对所有脚本阶段内容的可见性和感知,如果pod包含任何脚本阶段,则在安装pod时会向用户发出警告。
例如:
1 | spec.script_phase = { :name => 'Hello World', :script => 'echo "Hello World"' } |
1 | spec.script_phase = { :name => 'Hello World', :script => 'echo "Hello World"', :execution_position => :before_compile } |
1 | spec.script_phase = { :name => 'Hello World', :script => 'puts "Hello World"', :shell_path => '/usr/bin/ruby' } |
1 | spec.script_phase = { :name => 'Hello World', :script => 'echo "Hello World"', |
1 | spec.script_phase = { :name => 'Hello World', :script => 'echo "Hello World"', |
1 | spec.script_phases = [ |
文件格式
Podspecs应该位于存储库的根目录,文件的路径也应该相对于存储库的根目录指定。文件模式不支持遍历父目录(..)。文件模式可能包含以下通配符模式:
类型: *
匹配任何文件。可以被glob中的其他值限制。
*
将匹配所有文件c*
将匹配所有以c
开头的文件*c
是否会匹配所有以c
结尾的文件*c*
将匹配其中包含c
的所有文件(包括开头或结尾)
相当于正则表达式中的/.*/x
。
注意,这与类Unix隐藏文件(dotfiles)不匹配。为了在匹配结果中包含这些内容,必须使用{*,.}之类的内容。
类型:**
递归匹配目录。
类型:?
匹配任何一个字符。相当于正则表达式中的/.{1}/
。
类型:[set]
匹配集合中的任意字符。
其行为与正则表达式中的字符集完全相同,包括集取反([^a-z])。
类型:{p,q}
匹配文字p
或文字q
。
匹配的文字长度可能超过一个字符。可以指定两个以上的文字。
相当于regexp中的模式替换。
类型:\
转义字符。
例如:
在JSONKit的源根目录中对这些进行评估。
1 | "JSONKit.?" #=> ["JSONKit.h", "JSONKit.m"] |
source_files
多平台
pod 的源文件。
例如:
1 | spec.source_files = 'Classes/**/*.{h,m}' |
1 | spec.source_files = 'Classes/**/*.{h,m}', 'More_Classes/**/*.{h,m}' |
public_header_files
多平台
应用于标记公共头文件列表。
这些模式与源文件相匹配,以包含将公开给用户项目并从中生成文档的头。构建库时,这些头文件将显示在构建目录中。如果未指定公共头,则源文件中的所有头都视为公共。
例如:
1 | spec.public_header_files = 'Headers/Public/*.h' |
private_header_files
多平台
应用于标记私有头文件列表。
这些模式与公共头匹配(如果未指定公共头,则与所有头匹配),以排除那些不应向用户项目公开且不应用于生成文档的头。构建库时,这些头文件将显示在构建目录中。
未列为public或private的头文件将被视为private,但另外根本不会出现在生成目录中。
例如:
1 | spec.private_header_files = 'Headers/Private/*.h' |
vendored_frameworks
多平台
pod附带的动态库的路径。
例如:
1 | spec.ios.vendored_frameworks = 'Frameworks/MyFramework.framework' |
1 | spec.vendored_frameworks = 'MyFramework.framework', 'TheirFramework.framework' |
vendored_libraries
多平台
pod附带静态库的路径。
例如:
1 | spec.ios.vendored_library = 'Libraries/libProj4.a' |
1 | spec.vendored_libraries = 'libProj4.a', 'libJavaScriptCore.a' |
resource_bundles
多平台
这个属性允许定义应该为Pod构建的资源包的名称和文件。它们被指定为散列,其中的键表示捆绑包的名称以及它们应该包含的文件模式的值。
为了将Pod构建为静态库,我们强烈建议库开发人员采用资源包,因为使用resources属性可能会出现名称冲突。
捆绑包的名称应至少包括Pod的名称,以尽量减少名称冲突的可能性。
要为每个平台提供不同的资源,必须使用具有名称空间的捆绑包。
例如:
1 | spec.ios.resource_bundle = { 'MapBox' => 'MapView/Map/Resources/*.png' } |
1 | spec.resource_bundles = { |
resources
多平台
应复制到目标捆绑包中的资源列表。
为了将Pod构建为静态库,我们强烈建议库开发人员采用资源包,因为使用resources属性可能会出现名称冲突。此外,使用此属性指定的资源将直接复制到客户端目标,因此Xcode不会优化它们。
例如:
1 | spec.resource = 'Resources/HockeySDK.bundle' |
1 | spec.resources = ['Images/*.png', 'Sounds/*'] |
exclude_files
多平台
应从其他文件模式中排除的文件模式的列表。
例如:
1 | spec.ios.exclude_files = 'Classes/osx' |
1 | spec.exclude_files = 'Classes/**/unused.{h,m}' |
preserve_paths
多平台
下载后不应删除的任何文件。
默认情况下,CocoaPods会删除所有与其他任何文件模式都不匹配的文件。
例如:
1 | spec.preserve_path = 'IMPORTANT.txt' |
1 | spec.preserve_paths = 'Frameworks/*.framework' |
module_map
多平台
此pod集成为框架时应使用的模块映射文件。
默认情况下,CocoaPods基于规范中的公共头创建模块映射文件。
例如:
1 | spec.module_map = 'source/module.modulemap' |
子模块
库可以指定对另一个库、另一个库的子库或其自身的子库的依赖关系。
subspec
表示库模块的规范。
子空间参与双重层次。
一方面,规范自动继承所有它的子“子规范”(除非指定了默认子规范)作为依赖项。
另一方面,“子规范”继承父级属性的值,以便可以在祖先中指定属性的公共值。
虽然在实践中听起来很复杂,但这意味着子空间通常会做您所期望的事情:
1 | pod 'ShareKit', '2.0' |
将ShareKit与ShareKit/Evernote
、ShareKit/Facebook
等所有共享者一起安装,因为它们被定义为子空间。
1 | pod 'ShareKit/Twitter', '2.0' |
仅使用ShareKit/Twitter
、ShareKit/Pinboard
的源文件安装ShareKit。注意,在这种情况下,要编译的“子规范”需要源文件、依赖项和根规范定义的其他属性。CocoaPods足够聪明,可以处理由重复属性引起的任何问题。
例如:
带有不同源文件的子规范。
1 | subspec 'Twitter' do |sp| |
子空间引用对其他子空间的依赖关系。
1 | Pod::Spec.new do |s| |
嵌套subspecs。
1 | Pod::Spec.new do |s| |
requires_app_host
多平台
测试规范是否要求应用程序主机运行测试。这仅适用于测试规范。
例如:
1 | test_spec.requires_app_host = true |
app_host_name
1 | 必要时用作应用程序宿主的应用程序规范。 |
scheme
多平台
指定要用于此规范的scheme配置。
例如:
1 | spec.scheme = { :launch_arguments => ['Arg1'] } |
1 | spec.scheme = { :launch_arguments => ['Arg1', 'Arg2'], :environment_variables => { 'Key1' => 'Val1'} } |
支持的Keys:
1 | :launch_arguments |
test_spec
表示库的测试规范。在这里,您可以放置podspec的所有测试以及测试依赖项。
例如:
1 | Pod::Spec.new do |spec| |
app_spec
表示库的应用程序规范。在这里,你可以放置你的podspec的所有应用源文件以及应用依赖项。
例如:
1 | Pod::Spec.new do |spec| |
default_subspecs
应该用作首选依赖项的子空间名称数组。如果未指定,则规范要求其所有子空间作为依赖项。
您可以使用值:none
来指定编译此pod不需要任何子空间,并且所有子空间都是可选的。
默认情况下,Pod应该提供完整的库。用户可以微调其依赖关系,并排除不需要的子空间,一旦他们的需求是已知的。因此,很少需要此属性。如果存在提供替代不兼容实现的“子规范”,则使用它来选择默认值,或者排除很少需要的模块(尤其是当它们触发对其他库的依赖时)。
例如:
1 | spec.default_subspec = 'Core' |
1 | spec.default_subspecs = 'Core', 'UI' |
1 | spec.default_subspecs = :none |
多平台支持
规范可以存储仅特定于一个平台的值。
例如,可能需要存储仅特定于iOS项目的资源。
1 | spec.resources = 'Resources/**/*.png' |
iOS
提供指定iOS属性的支持。
例如:
1 | spec.ios.source_files = 'Classes/ios/**/*.{h,m}' |
osx
提供对指定OSX属性的支持。
例如:
1 | spec.osx.source_files = 'Classes/osx/**/*.{h,m}' |
macos
提供对指定OSX属性的支持。
例如:
1 | spec.osx.source_files = 'Classes/osx/**/*.{h,m}' |
tvos
提供指定tvOS属性的支持。
例如:
1 | spec.tvos.source_files = 'Classes/tvos/**/*.{h,m}' |
watchos
提供指定watchOS属性的支持。
例如:
1 | spec.watchos.source_files = 'Classes/watchos/**/*.{h,m}' |