[iOS] CocoaPods - Podspec文件配置

前言：在构建自己的组件库中，我们会经常编辑.podspec文件，进行一些配置项，但是有一些确实还是不太清楚，这里统一学习一下，内容翻译自官方文档：https://guides.cocoapods.org/syntax/podspec.html。

1. Specification （规范）

Specification描述了关于Pod库所有配置。包括从何处获取源代码、使用哪些文件、应用构建设置以及其他一般元数据(如名称、版本和描述)的详细信息。

可以直接使用pod spec create命令来为已有组件项目生成一个.podspec文件。但是一般我们创建组件时都会使用pod lib init命令，会同时生成.podspec文件。

来看一个比较简单的.podspec文件，内容如下：

Pod::Spec.new do |spec|
  spec.name         = 'Reachability'
  spec.version      = '3.1.0'
  spec.license      = { :type => 'BSD' }
  spec.homepage     = 'https://github.com/tonymillion/Reachability'
  spec.authors      = { 'Tony Million' => 'tonymillion@gmail.com' }
  spec.summary      = 'ARC and GCD Compatible Reachability Class for iOS and OS X.'
  spec.source       = { :git => 'https://github.com/tonymillion/Reachability.git', :tag => 'v3.1.0' }
  spec.source_files = 'Reachability.{h,m}'
  spec.framework    = 'SystemConfiguration'
end

再看一个比较详细的，内容如下：

Pod::Spec.new do |spec|
  spec.name          = 'Reachability'
  spec.version       = '3.1.0'
  spec.license       = { :type => 'BSD' }
  spec.homepage      = 'https://github.com/tonymillion/Reachability'
  spec.authors       = { 'Tony Million' => 'tonymillion@gmail.com' }
  spec.summary       = 'ARC and GCD Compatible Reachability Class for iOS and OS X.'
  spec.source        = { :git => 'https://github.com/tonymillion/Reachability.git', :tag => 'v3.1.0' }
  spec.module_name   = 'Rich'
  spec.swift_version = '4.0'

  spec.ios.deployment_target  = '9.0'
  spec.osx.deployment_target  = '10.10'

  spec.source_files       = 'Reachability/common/*.swift'
  spec.ios.source_files   = 'Reachability/ios/*.swift', 'Reachability/extensions/*.swift'
  spec.osx.source_files   = 'Reachability/osx/*.swift'

  spec.framework      = 'SystemConfiguration'
  spec.ios.framework  = 'UIKit'
  spec.osx.framework  = 'AppKit'

  spec.dependency 'SomeOtherPod'
end

有一些是我们常见的，有的是还没有见过的，这次都来了解并学习一下。

2. Root specification （根规范）

Root specification应用于整个pod库，包含分为必填和选填项。

选项	是否必填	描述
name	必填	库的名字
version	必填	库的版本号
swift_versions	选填	支持的Swift版本
cocoapods_version	选填	支持的cocoapods版本
authors	必填	作者信息
social_media_url	选填	作者第三方社交平台url
license	必填	许可证
homepage	必填	pod首页地址
readme	选填	readme文件地址
changelog	选填	changelog文件地址
source	必填	源文件地址
summary	必填	库描述
description	选填	库详细描述
screenshots	选填	库的截图
documentation_url	选填	库的文档url
prepare_command	选填	在安装前执行的脚本
static_framework	选填	是否是静态framework的形式
deprecated	选填	标记库是否被废弃
deprecated_in_favor_of	选填	标明库的名字被废弃

2.1 name （必填）

pod库的名字，我们搜索和导入的时候都会用到名字。

spec.name = 'AFNetworking'

2.2 version（必填）

pod库的版本号，一般都会和打的标签保持一致。

spec.version = '0.0.1'

2.3 swift_versions（选填）

规范支持的Swift版本。CocoaPods会将“4”视为“4.0”，而不是“4.1”或“4.2”。

注意:Swift编译器主要接受主版本，有时也会支持小版本。虽然CocoaPods允许指定小版本或补丁版本，但Swift编译器可能不会完全遵守。

# 支持多种写法
spec.swift_versions = ['3.0']
spec.swift_versions = ['3.0', '4.0', '4.2']
spec.swift_version = '3.0'
spec.swift_version = '3.0', '4.0'

2.4 cocoapods_version（选填）

规范支持的CocoaPods版本。

spec.cocoapods_version = '>= 0.36'

2.5 authors（必填）

作者。

spec.author = 'Darth Vader'
spec.authors = 'Darth Vader', 'Wookiee'
spec.authors = { 'Darth Vader' => 'darthvader@darkside.com',
                 'Wookiee'     => 'wookiee@aggrrttaaggrrt.com' }

2.6 social_media_url（必填）

Pod的社交媒体联系人的URL， CocoaPods网络服务可以使用这个。

spec.social_media_url = 'https://twitter.com/cocoapods'
spec.social_media_url = 'https://groups.google.com/forum/#!forum/cocoapods'

2.7 license （必填）

Pod许可证。

spec.license = 'MIT'
spec.license = { :type => 'MIT', :file => 'MIT-LICENSE.txt' }
spec.license = { :type => 'MIT', :text => <<-LICENSE
                   Copyright 2012
                   Permission is granted to...
                 LICENSE
               }

2.8 homepage （必填）

Pod主页的URL。

spec.homepage = 'http://www.example.com'

2.9 readme（选填）

此pod版本的README markdown文件的URL。

spec.readme = 'https://www.example.com/Pod-1.5-README.md'

2.10 changelog（选填）

此pod版本的CHANGELOG markdown文件的URL。

spec.changelog = 'https://www.example.com/Pod-1.5-CHANGELOG.md'

2.11 source（选填）

应该从何处检索库的位置。

• 使用tag指定一个Git源文件，比较常用：

spec.source = { :git => 'https://github.com/AFNetworking/AFNetworking.git',
                :tag => spec.version.to_s }

• 使用以'v'和子模块为前缀的标签

spec.source = { :git => 'https://github.com/typhoon-framework/Typhoon.git',
                :tag => "v#{spec.version}", :submodules => true }

还有一些不常用的，比如支持下载zip文件，可以从官网上看到。

支持的keys：

:git => :tag, :branch, :commit, :submodules

:svn => :folder, :tag, :revision

:hg => :revision

:http => :flatten, :type, :sha256, :sha1, :headers

2.12 summary（选填）

对Pod的简短描述(最多140个字符)。

spec.summary = 'Computes the meaning of life.'

2.13 description（选填）

对Pod的描述比summary更详细。

spec.description = <<-DESC
                     Computes the meaning of life.
                     Features:
                     1. Is self aware
                     ...
                     42. Likes candies.
                   DESC

2.14 screenshots（选填）

展示Pod截图的url列表。CocoaPods推荐使用gif格式。

spec.screenshot  = 'http://dl.dropbox.com/u/378729/MBProgressHUD/1.png'
spec.screenshots = [ 'http://dl.dropbox.com/u/378729/MBProgressHUD/1.png',
                     'http://dl.dropbox.com/u/378729/MBProgressHUD/2.png' ]

2.15 documentation_url（选填）

一个可选的Pod文档URL，默认为CocoaDocs生成的库URL。

spec.documentation_url = 'http://www.example.com/docs.html'

2.16 prepare_command（选填）

下载Pod后执行的bash脚本。该命令可用于创建、删除和修改下载的任何文件，并且将在该规范的其他文件属性的任何路径被收集之前运行该命令。

此命令在清理Pod和创建Pod project项目之前执行。工作目录为Pod的根目录。

如果pod导入时使用了:path选项，则不会执行此命令。

spec.prepare_command = 'ruby build_files.rb'
spec.prepare_command = <<-CMD
                        sed -i 's/MyNameSpacedHeader/Header/g' ./**/*.h
                        sed -i 's/MyNameOtherSpacedHeader/OtherHeader/g' ./**/*.h
                   CMD

2.17 static_framework（选填）

如果use_frameworks!指定时，pod应该包含一个静态库framework。

spec.static_framework = true

2.18 deprecated（选填）

标记库是否已经废弃不用。

spec.deprecated = true

2.19 deprecated_in_favor_of（选填）

这个Pod库的名字已经被弃用了。

spec.deprecated_in_favor_of = 'NewMoreAwesomePod'

3. Platform

规范应该指明支持库的平台和相应的部署目标。

3.1 platform

支持当前Pod库的平台。不填则表示所有平台都支持该Pod库。当支持多个平台时，你应该使用下面的deployment_target。

spec.platform = :osx, '10.8'
spec.platform = :ios
spec.platform = :osx

3.2 deployment_target

支持platform的最小部署目标。

与platform属性相反，deployment_target属性允许指定支持此pod的多个平台，就是为每个platform指定不同的部署目标。

spec.ios.deployment_target = '6.0'
spec.osx.deployment_target = '10.8'

4. Build settings

在该组中列出了与应用构建环境配置相关的属性。

4.1 dependency

标明对其他pod库或者子库的依赖。

如果这里指定版本过于严格，会限制它们与其他pod的兼容性。

spec.dependency 'AFNetworking', '~> 1.0'
spec.dependency 'AFNetworking', '~> 1.0', :configurations => ['Debug']
spec.dependency 'AFNetworking', '~> 1.0', :configurations => :debug
spec.dependency 'RestKit/CoreData', '~> 0.20.0'
spec.ios.dependency 'MBProgressHUD', '~> 0.5'

4.2 info_plist (multi-platform)

要添加到生成的Info.plist中的键值对。

对于library specs，这些值将合并到生成的framework的Info.plist中，它对静态库没有影响，不支持subspecs。对于app specs，这些值将合并到主应用的Info.plist中。

spec.info_plist = {
  'CFBundleIdentifier' => 'com.myorg.MyLib',
  'MY_VAR' => 'SOME_VALUE'
}

4.3 requires_arc （默认为true）

requires_arc允许指定哪些source_files使用ARC。可以设置为true表示所有source_files使用ARC。不使用ARC的文件会有-fno-objc-arc编译标志。

spec.requires_arc = true
spec.requires_arc = 'Classes/Arc'
spec.requires_arc = ['Classes/*ARC.m', 'Classes/ARC.mm']

4.4 frameworks (multi-platform)

用户的target需要链接的系统framework列表。

spec.ios.framework = 'CFNetwork'
spec.frameworks = 'QuartzCore', 'CoreData'

4.5 weak_frameworks (multi-platform)

用户的目标需要弱链接的框架列表。

spec.weak_framework = 'Twitter'
spec.weak_frameworks = 'Twitter', 'SafariServices'

4.6 libraries (multi-platform)

用户的目标(应用程序)需要链接的系统库的列表。

spec.ios.library = 'xml2'
spec.libraries = 'xml2', 'z'

4.7 compiler_flags (multi-platform)

应该传递给编译器的标志列表。

spec.compiler_flags = '-DOS_OBJECT_USE_OBJC=0', '-Wno-format'

4.8 pod_target_xcconfig (multi-platform)

要添加到最终私有pod target 的 xcconfig文件中的任何标志。

spec.pod_target_xcconfig = { 'OTHER_LDFLAGS' => '-lObjC' }

4.9 user_target_xcconfig (multi-platform)

指定要添加到最终聚合target（项目工程target）的xcconfig文件的标志。

不建议使用此属性，因为Pods不应该污染用户项目的构建设置，这可能会导致冲突。建议使用pod_target_xcconfig。

spec.user_target_xcconfig = { 'MY_SUBSPEC' => 'YES' }

4.10 prefix_header_contents (multi-platform)

要注入到pod项目前缀头中的任何内容。

不建议使用此属性，因为Pods不应该污染其他库或用户项目的前缀头。

spec.prefix_header_contents = '#import <UIKit/UIKit.h>'
spec.prefix_header_contents = '#import <UIKit/UIKit.h>', '#import <Foundation/Foundation.h>'

4.11 prefix_header_file (multi-platform)

要注入到pod项目的前缀头文件中的前缀头文件的路径。

不建议使用文件路径选项，因为Pods不应该污染其他库或用户项目的前缀头。

spec.prefix_header_file = 'iphone/include/prefix.pch'
spec.prefix_header_file = false

4.12 module_name

该规范生成的用于framework / clang module 的名称，而不是默认名称(如果设置header_dir，否则为规范名称)。

spec.module_name = 'Three20'

4.13 header_dir (multi-platform)

存放头文件的目录，这样它们就不会破坏include。

spec.header_dir = 'Three20Core'

4.14 header_dir (multi-platform)

保存头文件的文件夹结构的目录。如果没有提供，头文件将被flattened。

spec.header_dir = 'Three20Core'

4.15 script_phases (multi-platform)

此属性允许定义脚本阶段，以作为Pod编译的一部分执行。与prepare command不同，脚本阶段作为xcodebuild的一部分执行，它们还可以使用编译期间设置的所有环境变量。

Pod可以提供多个脚本阶段来执行，它们将按照声明的顺序添加。

注意:为了提供所有脚本阶段的内容的可见性，如果pod包含任何脚本，安装时将向用户显示一个警告。

spec.script_phase = { :name => 'Hello World', :script => 'echo "Hello World"' }
spec.script_phase = { :name => 'Hello World', :script => 'echo "Hello World"', :execution_position => :before_compile }
spec.script_phase = { :name => 'Hello World', :script => 'puts "Hello World"', :shell_path => '/usr/bin/ruby' }
spec.script_phase = { :name => 'Hello World', :script => 'echo "Hello World"',
  :input_files => ['/path/to/input_file.txt'], :output_files => ['/path/to/output_file.txt']
}
spec.script_phase = { :name => 'Hello World', :script => 'echo "Hello World"',
  :input_file_lists => ['/path/to/input_files.xcfilelist'], :output_file_lists => ['/path/to/output_files.xcfilelist']
}
spec.script_phases = [
    { :name => 'Hello World', :script => 'echo "Hello World"' },
    { :name => 'Hello Ruby World', :script => 'puts "Hello World"', :shell_path => '/usr/bin/ruby' },
  ]

5. File patterns（文件模式）

5.1 File patterns

Podspecs应该位于库文件夹的根目录，并且文件的路径也应该相对于存储库的目录指定。文件模式不支持遍历父目录(…)． 文件模式可能包含以下通配符模式:

5.1.1 Pattern: *

匹配任何文件，可以被glob中的其他值限制：

* 匹配所有文件
c* 匹配以c开头的文件
*c 匹配以c结尾的文件
*c*匹配包含c的文件

5.1.2 Pattern: **

目录递归地匹配。

5.1.3 Pattern: ?

匹配任意一个字符。相当于 正则表达式中的/.{1}/。

5.1.4 Pattern: [set]

匹配集合中的任意一个字符。
行为与正则表达式中的字符集完全一样，包括反集([^a-z])。

5.1.4 Pattern: {p,q}

匹配字面值p或字面值q。等价于正则表达式中的模式变换。

5.1.5 Pattern: \

转义下一个元字符。

示例：

"JSONKit.?"    #=> ["JSONKit.h", "JSONKit.m"]
"*.[a-z][a-z]" #=> ["CHANGELOG.md", "README.md"]
"*.[^m]*"      #=> ["JSONKit.h"]
"*.{h,m}"      #=> ["JSONKit.h", "JSONKit.m"]
"*"            #=> ["CHANGELOG.md", "JSONKit.h", "JSONKit.m", "README.md"]

5.2 source_files (multi-platform)

pod库中包含的源文件。

spec.source_files = 'Classes/**/*.{h,m}'
spec.source_files = 'Classes/**/*.{h,m}', 'More_Classes/**/*.{h,m}'

5.3 public_header_files (multi-platform)

作为公共头的文件模式列表。

这些文件模式将与源文件进行匹配，以包含将向主项目公开的头文件，并从中生成文档。当构建库时，这些头文件将出现在构建目录中。如果没有指定公共头文件，那么source_files中的所有头文件都被认为是公共的。

spec.public_header_files = 'Headers/Public/*.h'

5.4 project_header_files (multi-platform)

作为项目头的文件模式列表。

这些文件模式将与public headers进行匹配，以排除那些不应公开给用户项目和不应用于生成文档的headers。当构建库时，这些头文件将不会出现在构建目录中。

spec.project_header_files = 'Headers/Project/*.h'

5.5 private_header_files (multi-platform)

作为私有头的文件模式列表。

这些模式将与public headers进行匹配，以排除那些不应公开给用户项目和不应用于生成文档的标头。当构建库时，这些头文件将出现在构建目录中。

未被列为公共、项目或私有文件的头文件会出现在构建目录中。

spec.private_header_files = 'Headers/Private/*.h'

5.6 vendored_frameworks (multi-platform)

Pod所依赖的的framework的路径，同时支持.framework和.xcframework包。这些框架将提供给Pod和Pod的消费者。

spec.ios.vendored_frameworks = 'Frameworks/MyFramework.framework'
spec.vendored_frameworks = 'MyFramework.framework', 'TheirFramework.xcframework'

5.7 vendored_libraries (multi-platform)

Pod所依赖的库(.a文件)的路径。

spec.ios.vendored_library = 'Libraries/libProj4.a'
spec.vendored_libraries = 'libProj4.a', 'libJavaScriptCore.a'

5.8 on_demand_resources (multi-platform)

应复制到目标target中的随需应变资源的哈希值。这里指定的资源将自动成为集成此pod的target的资源构建阶段的一部分。

由pods指定的tag是由CocoaPods管理的。如果一个标签被重命名、更改或删除，那么CocoaPods也会在工程target中进行更新。

s.on_demand_resources = {
  'Tag1' => 'file1.png'
}
s.on_demand_resources = {
  'Tag1' => ['file1.png', 'file2.png']
}
s.on_demand_resources = {
  'Tag1' => { :paths => ['file1.png', 'file2.png'], :category => :download_on_demand }
}
s.on_demand_resources = {
  'Tag1' => { :paths => ['file1.png', 'file2.png'], :category => :initial_install }
}

5.9 resource_bundles (multi-platform)

这个属性允许为pod构建使用的资源包定义name。就是一个键值对，其中key表示包的名称，value表示它们应该包含的文件模式的值。

为了将Pod构建为一个静态库，推荐采用resource_bundles，因为使用resources属性可能会产生名称冲突。

包的名称至少应该包含Pod的名称，以尽量减少名称冲突的机会。

spec.ios.resource_bundle = { 'MapBox' => 'MapView/Map/Resources/*.png' }
spec.resource_bundles = {
    'MapBox' => ['MapView/Map/Resources/*.png'],
    'MapBoxOtherResources' => ['MapView/Map/OtherResources/*.png']
  }

5.10 resources (multi-platform)

应该复制到目标target bundle中的资源列表。

为了将Pod构建为一个静态库，强烈建议采用resource_bundles，因为使用resources属性可能会产生名称冲突。此外，用这个属性指定的资源会直接复制到客户端目标中，因此它们不会被Xcode优化。

spec.resource = 'Resources/HockeySDK.bundle'
spec.resources = ['Images/*.png', 'Sounds/*']

5.11 exclude_files (multi-platform)

应该从其他文件模式中排除的文件模式列表。

spec.ios.exclude_files = 'Classes/osx'
spec.exclude_files = 'Classes/**/unused.{h,m}'

5.12 preserve_paths (multi-platform)

下载后不应删除的任何文件。

默认情况下，CocoaPods删除所有与任何其他文件模式不匹配的文件。

spec.preserve_path = 'IMPORTANT.txt'
spec.preserve_paths = 'Frameworks/*.framework'

5.13 module_map (multi-platform)

当此pod集成为framework时应该使用的模块映射文件。

false表示不应该生成默认的CocoaPods modulemap文件。
true为默认值，表示应该生成默认的CocoaPods modulemap文件。

默认情况下，CocoaPods根据规范中的公共头文件创建模块映射文件。

spec.module_map = 'source/module.modulemap'
spec.module_map = false