lightingbolt

文档更新说明

• 2012-12-02 v1.0 初稿
• 2014-01-08 v1.1 增加设置ruby淘宝源相关内容
• 2014-05-25 v2.0 增加国内spec镜像、使用私有pod、podfile.lock、创建spec文件等内容

CocoaPods简介

每种语言发展到一个阶段，就会出现相应的依赖管理工具，例如Java语言的Maven，nodejs的npm。随着iOS开发者的增多，业界也出现了为iOS程序提供依赖管理的工具，它的名字叫做：CocoaPods。

CocoaPods项目的源码在Github上管理。该项目开始于2011年8月12日，经过多年发展，现在已经成为iOS开发事实上的依赖管理标准工具。开发iOS项目不可避免地要使用第三方开源库，CocoaPods的出现使得我们可以节省设置和更新第三方开源库的时间。

在我开发猿题库客户端时，其使用了24个第三方开源库。在没有使用CocoaPods以前，我需要:

1. 把这些第三方开源库的源代码文件复制到项目中，或者设置成git的submodule。
2. 对于这些开源库通常需要依赖系统的一些framework，我需要手工地将这些framework一一增加到项目依赖中，比如通常情况下，一个网络库就需要增加以下framework: CFNetwork, SystemConfiguration, MobileCoreServices, CoreGraphics, zlib。
3. 对于某些开源库，我还需要设置-licucore或者 -fno-objc-arc等编译参数
4. 管理这些依赖包的更新。

这些体力活虽然简单，但毫无技术含量并且浪费时间。在使用CocoaPods之后，我只需要将用到的第三方开源库放到一个名为Podfile的文件中，然后执行pod install。CocoaPods就会自动将这些第三方开源库的源码下载下来，并且为我的工程设置好相应的系统依赖和编译参数。

CocoaPods的安装和使用介绍安装

安装方式异常简单, Mac下都自带ruby，使用ruby的gem命令即可下载安装：

1 2 $ sudo gem install cocoapods $ pod setup

如果你的gem太老，可能也会有问题，可以尝试用如下命令升级gem:

1 sudo gem update --system

另外，ruby的软件源rubygems.org因为使用的亚马逊的云服务，所以被墙了，需要更新一下ruby的源，如下代码将官方的ruby源替换成国内淘宝的源：

1 2 3 gem sources --remove https://rubygems.org/ gem sources -a https://ruby.taobao.org/ gem sources -l

还有一点需要注意，pod setup在执行时，会输出Setting up CocoaPods master repo，但是会等待比较久的时间。这步其实是Cocoapods在将它的信息下载到 ~/.cocoapods目录下，如果你等太久，可以试着cd到那个目录，用du -sh *来查看下载进度。你也可以参考本文接下来的使用cocoapods的镜像索引一节的内容来提高下载速度。

使用CocoaPods的镜像索引

所有的项目的Podspec文件都托管在https://github.com/CocoaPods/Specs。第一次执行pod setup时，CocoaPods会将这些podspec索引文件更新到本地的 ~/.cocoapods/目录下，这个索引文件比较大，有80M左右。所以第一次更新时非常慢，笔者就更新了将近1个小时才完成。

一个叫akinliu的朋友在gitcafe和oschina上建立了CocoaPods索引库的镜像，因为gitcafe和oschina都是国内的服务器，所以在执行索引更新操作时，会快很多。如下操作可以将CocoaPods设置成使用gitcafe镜像：

1 2 3 pod repo remove master pod repo add master https://gitcafe.com/akuandev/Specs.git pod repo update

将以上代码中的 https://gitcafe.com/akuandev/Specs.git 替换成 https://git.oschina.net/akuandev/Specs.git 即可使用oschina上的镜像。

使用CocoaPods

使用时需要新建一个名为Podfile的文件，以如下格式，将依赖的库名字依次列在文件中即可

1 2 3 4 5 platform :ios pod 'JSONKit', '~> 1.4' pod 'Reachability', '~> 3.0.0' pod 'ASIHTTPRequest' pod 'RegexKitLite'

然后你将编辑好的Podfile文件放到你的项目根目录中，执行如下命令即可：

1 2 cd "your project home" pod install

现在，你的所有第三方库都已经下载完成并且设置好了编译参数和依赖，你只需要记住如下2点即可：

1. 使用CocoaPods生成的 .xcworkspace 文件来打开工程，而不是以前的 .xcodeproj 文件。
2. 每次更改了Podfile文件，你需要重新执行一次pod update命令。

查找第三方库

你如果不知道cocoaPods管理的库中，是否有你想要的库，那么你可以通过pod search命令进行查找，以下是我用pod search json查找到的所有可用的库：

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 $ pod search json -> AnyJSON (0.0.1) Encode / Decode JSON by any means possible. - Homepage: https://github.com/mattt/AnyJSON - Source: https://github.com/mattt/AnyJSON.git - Versions: 0.0.1 [master repo] -> JSONKit (1.5pre) A Very High Performance Objective-C JSON Library. - Homepage: https://github.com/johnezang/JSONKit - Source: git://github.com/johnezang/JSONKit.git - Versions: 1.5pre, 1.4 [master repo] // ...以下省略若干行

关于.gitignore

当你执行pod install之后，除了Podfile外，CocoaPods还会生成一个名为Podfile.lock的文件，你不应该把这个文件加入到.gitignore中。因为Podfile.lock会锁定当前各依赖库的版本，之后如果多次执行pod install 不会更改版本，要pod update才会改Podfile.lock了。这样多人协作的时候，可以防止第三方库升级时造成大家各自的第三方库版本不一致。

CocoaPods的这篇官方文档也在What is a Podfile.lock一节中介绍了Podfile.lock的作用，并且指出：

This file should always be kept under version control.

为自己的项目创建podspec文件

我们可以为自己的开源项目创建podspec文件，首先通过如下命令初始化一个podspec文件：

1 pod spec create your_pod_spec_name

该命令执行之后，CocoaPods会生成一个名为your_pod_spec_name.podspec的文件，然后我们修改其中的相关内容即可。

具体步骤可以参考这两篇博文中的相关内容：《如何编写一个CocoaPods的spec文件》 和《Cocoapods 入门》。

使用私有的pods

我们可以直接指定某一个依赖的podspec，这样就可以使用公司内部的私有库。该方案有利于使企业内部的公共项目支持CocoaPods。如下是一个示例：

1 pod 'MyCommon', :podspec => 'https://yuantiku.com/common/myCommon.podspec'

不更新podspec

CocoaPods在执行pod install和pod update时，会默认先更新一次podspec索引。使用--no-repo-update参数可以禁止其做索引更新操作。如下所示：

1 2 pod install --no-repo-update pod update --no-repo-update

生成第三方库的帮助文档

如果你想让CococaPods帮你生成第三方库的帮助文档，并集成到Xcode中，那么用brew安装appledoc即可：

1 brew install appledoc

关于appledoc，我在另一篇博客《使用Objective-C的文档生成工具:appledoc》中有专门介绍。它最大的优点是可以将帮助文档集成到Xcode中，这样你在敲代码的时候，按住opt键单击类名或方法名，就可以显示出相应的帮助文档。

原理

大概研究了一下CocoaPods的原理，它是将所有的依赖库都放到另一个名为Pods项目中，然后让主项目依赖Pods项目，这样，源码管理工作都从主项目移到了Pods项目中。发现的一些技术细节有：

1. Pods项目最终会编译成一个名为libPods.a的文件，主项目只需要依赖这个.a文件即可。
2. 对于资源文件，CocoaPods提供了一个名为Pods-resources.sh的bash脚本，该脚本在每次项目编译的时候都会执行，将第三方库的各种资源文件复制到目标目录中。
3. CocoaPods通过一个名为Pods.xcconfig的文件来在编译时设置所有的依赖和参数。

愿大家玩得开心～

介绍

最近一直在搞cocoapods。 ios 这么多年终于有一个好使的包管理了。真的好激动好激动。。。 之前开发一些App的时候，在一开始的时候，总是需要手动添加framework， library，设置一些 search path，有时候还会忘记那么几个，然后出来一大堆的link error。当一些library更新的时候，还需要自己手动去更换。3句话说就是

1. 手动增加framework，library
2. 手动增加编译参数
3. 手动维护代码更新

完全是一大堆的体力活，当然，这些简单的配置和复制并不会花费太多的时间，但是，还是觉得在浪费生命，而这时候CocoaPods就出来了。我们只需要设置一个Podfile文件，执行

$ pod install

CocoaPods会帮我们下载好代码，设置好编译参数，配置好framework， library。

安装和更新$ sudo gem install cocoapods 使用

在project根目录下，create Podfile文件，下面一个例子

platform :ios, '5.0' pod 'CURestKit', '~>1.0.1' pod 'SDWebImage','~>3.4' pod 'MBProgressHUD', '~> 0.7' pod 'UALogger', '~> 0.2.3'

CocoaPods 会帮我们从git clone下来配置好的这些代码。后面的部分表示代码的版本号，一般来说和tag挂钩。

配置好Podfile之后，执行

$ pod install

则会帮我们配置好这些项目。并生成一个XXXX.xcworkspace。 以后project使用这个文件就可以了。CocoaPods其实就是帮我们配置一个静态库作为项目的依赖。

CocoaPods里面有大量的代码，现在最新的版本安装后是在这里

~/.cocoapods/repo/master/ 制作自己的项目配置

实际开发过程中，我们还有不少代码需要被改动，而CocoaPods上面的代码，大部分都比较旧，都是很稳定的代码，当然也有一些不能用的（大部分是国内的公司做的，大家都懂的）。另外还有一些我们自己写的一些其他代码，暂时还么有被CocoaPods收录的。这时候我们就需要配置自己的项目啦。

这里是我的一个项目配置例子。cocoapods的配置文件就是一个 *.podspec的文件，这是一个例子文件名ShareCenter.podspec。这是一个典型的ruby，

Pod::Spec.new do |s| s.name = "ShareCenter" s.version = "2.0" s.summary = "share client include sina weibo ,tencent weibo, renren" s.description = <<-DESC share client include sina weibo ,tencent weibo, renren DESC s.homepage = "https://github.com/studentdeng/ShareCenterExample" s.license = 'MIT' s.author = { "curer" => "studentdeng@hotmail.com" } s.platform = :ios, '5.0' s.source = { :git => "https://github.com/studentdeng/ShareCenterExample.git", :tag => s.version.to_s } s.source_files = 'ShareCenter', 'ShareCenter/**/*.{h,m}' s.frameworks = 'QuartzCore', 'Security', 'CoreGraphics', 'AudioToolbox' s.library = 'sqlite3.0' s.vendored_libraries = 'ShareCenter/Vender/sina/libWeiboSDK/libWeiboSDK.a' s.prefix_header_contents = <<-EOS #ifdef __OBJC__ #import "ROConnect.h" #endif /* __OBJC__*/ EOS end

这个基本上都是自解释的，这里有几个需要说明一下

s.source s.source_files

这里的 source 我们看出是一个git 的地址，这里我们调试的时候，可以先暂时设置成本地git，调试完毕之后就可以发布 增加tag。想要最新的代码只需要这样设置就好

{ :git => "https://github.com/studentdeng/ShareCenterExample.git"}

我们的git项目中，并不是所有的代码都需要被引用到我们的代码中，通常project还会包括一些example，test cases等，这里的 source_files 就是用来指定一些文件夹，或是文件。我这里的设置也很容易理解，就是ShareCenter下面的递归后的所有后缀是h、m的子文件。

s.frameworks s.library

这里配置的就是我们的framework 和 library，这里注意一下library的名字规则就好。

vendored_libraries

这里用来指定外部的静态库。这里我们指定了sina sso认证的SDK

s.prefix_header_contents

这里用来指定预编译的配置，这里一定要鄙视一下renren的超级渣渣SDK。这里提供一种解决方法。

部署我们的配置到cocoapods中

cocoapods的代码配置文件是在这里Specs

这里最好是去fork一个自己的project，然后保存一个自己或是团队的配置，这样不会在更新cocoapods的时候，丢掉自己的配置。当然，如果觉得自己搞的还不错，也可以去pull requests。

在之前提到的目录~/.cocoapods/repo/master/ 下面，我们可以看到已经有超级多的项目了，我们可以也可以通过

$ pod search XXX

来查找项目，或是直接在这个文件夹下面找，可以学习不少project的配置技巧，我这里也是从他们学到的。

最后添加一个project的配置是这样子的。

例如上面的例子， 在~/.cocoapods/repo/master/ 下面创建一个文件夹ShareCenter，然后在创建一个2.0的文件夹表示这是version2.0的配置。 然后在把之前的ShareCenter.podspec复制到2.0目录下面。

也就是最后的目录是这样子的

~/.cocoapods/repo/master/ShareCenter/2.0/ShareCenter.podspec

如果希望更多的了解cocoapods，还是需要去Github上面 :D

CocoaPods命令介绍  

在  上一篇文章 中，已经介绍过CocoaPods的几条基本命令。  pod setup 用于初始化本地第三方库的Spec描述文件，所有的spec文件存都存放在  ~/.cocoapods 目录中。  pod install 用来安装或删除Podfile文件声明中的第三方依赖库。下面继续介绍其它一些命令。  

Shell代码  

  

1. $ pod list  
2. # 列出所有可用的第三方库  

Shell代码  

  

1. $ pod search query  

搜索名称包含  query 的类库，  query 可以替换为你想搜索的名字（如json)，不区分大小写。也可以使用  pod search --full query 命令作更仔细的搜索，该命令不但搜索类库的名称，同时还搜索类库的描述文本，所以搜索速度也相对慢一些。  

pod list 和  pod search 命令只搜索存在于本地  ~/.cocoapods 文件夹的所有第三方库，并不会连接到远程服务器。如果你要从服务器更新本地第三方库的描述文件，可以:  

Shell代码  

  

1. $ pod repo update master  
2. 创建自己项目的Podspec描述文件  

CocoaPods还是一个相对年轻的项目，所有的项目的Podspec文件都托管在 https://github.com/CocoaPods/Specs 。可能有一些库并未收录其中。下面我们通过为微博sso认证登录库编写Podspec文件来学习相关的概念。  

初始化一个Podspec文件  

Shell代码  

  

1. $ pod spec create weibo_ios_sdk_sso-oauth  

该命令将在本目录产生一个名为  weibo_ios_sdk_sso-oauth.podspec 的文件。用编辑器打开该文件，里面已经有非常丰富的说明文档。下面我们介绍如何声明第三方库的代码目录和资源目录，还有该第三方库所依赖ios核心框架和第三方库。  

去除所有的注释，podspec文件如下所示:  

Shell代码  

  

1. Pod::Spec.new do |s|  
2.   s.name     = 'ADVProgressBar'  
3.   s.version  = '0.0.1'  
4.   s.license  = 'MIT'  
5.   s.summary  = 'Progress Bar Design with Percentage values.'  
6.   s.homepage = 'https://github.com/appdesignvault'  
7.   s.author   = { 'appdesignvault' => 'appdesignvault' }  
8.   s.source   = { :git => 'https://github.com/appdesignvault/ADVProgressBar.git', :commit => 'f17b15c15574d6d101cd5fcfd58239e16e806647' }  
9.   s.platform = :ios    
10.   s.source_files = 'ADVProgressBar/Classes/*.{h,m}'  
11.   s.resources = "ADVProgressBar/Resources/*.png"  
12.   s.framework = 'UIKit'  
13.   
14.   s.requires_arc = true    
15. end  

其中  s.name 和  s.summary 用来声明库的名称和一个简短的说明文档。  pod search 命令就是根据这两项内容作为搜索文本的。  s.homepage 声明库的主页，  s.version 库原代码的版本，  s.license所采用的授权版本，  s.author 库的作者。  

s.source  声明原代码的地址，以微博sso认证登录库为例，它托管在

Github代码  

  

1. https://github.com/mobileresearch/weibo_ios_sdk_sso-oauth  

中，在其未尾加上  .git 扩展名就是库的原代码地址了，所以该行应声明为:  

Shell代码  

  

1. s.source = { :git => 'https://github.com/mobileresearch/weibo_ios_sdk_sso-oauth.git'}  

对于很多第三方库而言，在发布的时候都会打上一个  tag ，如版本  0.0.1 就会打上一个名为v0.0.1的tag，但是  weibo_ios_sdk_sso-oauth 库还未打上所何tag，我们可以选择一个最新的commit来作为该库0.0.1版的代码。  s.source 最终如下：  

Shell代码  

  

1. s.source = { :git => 'https://github.com/mobileresearch/weibo_ios_sdk_sso-oauth.git', :commit => '68defea78942ecc782ffde8f8ffa747872af226d'}  

以后我们可以根据该库不同的版本创建相应的podspec文件，例如0.0.2，0.1.0等。  

让我们在浏览器中看一下weibo_ios_sdk_sso-oauth的目录结构:  

List代码  

  

1. --  
2. |  
3. +-- demo  
4. |  
5. +-- src  
6. |  
7. +-- .gitignore  
8. |  
9. +-- README.md  

demo目录保存一个示例项目，src才是库的原代码目录。src的目录结构如下:  

List代码  

  

1. -- src  
2.     |  
3.     +-- JSONKit  
4.     |  
5.     +-- SinaWeibo  
6.     |  
7.     +-- sinaweibo_ios_sdk.xcodeproj  
8.     |  
9.     +-- SinaWeibo-Prefix.pch  

JSONKit目录说明这个库本身依赖于JSONKit第三方库。我们可以在podspec文件中的 s.dependency 声明段中声明。SinaWeibo目录才是包含所有原代码的目录，我们需要在 s.source_files 中声明  

Shell代码  

  

1. s.source_files = 'src/SinaWeibo/*.{h,m}'  

前一部分src/SinaWeibo/是一个相对目录，目录的层级关系一定要跟代码库的保持一致。最后一部分 *.{h,m} 是一个类似正则表达式的字符串，表示匹配所有以.h和.m为扩展名的文件。  

src/SinaWeibo/目录 下还有一个  SinaWeibo.bundle目录 ，该目录存放一些资源文件（如图片等），这些文件并不需要进行编译。可以使用  s.resourcs 声明  

Shell代码  

  

1. s.resources = "src/SinaWeibo/SinaWeibo.bundle/**/*.png"  

前一部分跟上面相同，  ** 表示匹配所有子目录，  *.png 表示所有以.png为扩展名的图片文件。  

通过查看代码我们知道，weibo_ios_sdk_sso-oauth还依赖一个ios的核心库QuartzCore  

Shell代码  

  

1. s.framework = 'QuartzCore'  

在前面我们已经说过，weibo_ios_sdk_sso-oauth库自身也依赖于另外一个第三方库JSONKit，声明如下:  

Shell代码  

  

1. s.dependency 'JSONKit', '~> 1.4'  

这行声明与Podfile文件中的声明类似。  

最终的结果如下：  

Shell代码  

  

1. Pod::Spec.new do |s|  
2.   s.name         = "weibo_ios_sdk_sso-oauth"  
3.   s.version      = "0.0.1"  
4.   s.summary  = 'weibo.com sso oauth, 微博sso认证登录功能'  
5.   s.homepage     = "https://github.com/mobileresearch/weibo_ios_sdk_sso-oauth"  
6.   s.license      = 'MIT'  
7.   s.author       = {'mobileresearch' => 'mobileresearch'}  
8.   s.source       = { :git => 'https://github.com/mobileresearch/weibo_ios_sdk_sso-oauth.git', :commit => '68defea78942ecc782ffde8f8ffa747872af226d' }  
9.   s.platform = :ios  
10.   s.source_files = 'src/SinaWeibo/*.{h,m}'  
11.   s.resources = "src/SinaWeibo/SinaWeibo.bundle/**/*.png"  
12.   s.framework  = 'QuartzCore'  
13.   s.dependency 'JSONKit', '~> 1.4'  
14. end  

可以将该spec文件保存到本机的~/.cocoapods/master/目录中仅供自己使用，也可以将其提交到CocoaPods/Specs代码库中。下面我们将其保存到本机中  

Shell代码  

  

1. $ mkdir -p ~/.cocoapods/master/weibo_ios_sdk_sso-oauth/0.0.1  
2. $ cp weibo_ios_sdk_sso-oauth.podspec ~/.cocoapods/master/weibo_ios_sdk_sso-oauth/0.0.1  

是否可以通过搜索找到该库:  

Shell代码  

  

1. $ pod search weibo  

同样在需要依赖于weibo_ios_sdk_sso-oauth这个库的项目，可以将下列添加到项目的Podfile文件中  

Shell代码  

  

1. pod 'weibo_ios_sdk_sso_oauth', '0.0.1'  

保存文件，并用  pod install 安装weibo_ios_sdk_sso-oauth库。