CocoaPods iOS 开源库管理

1、CocoaPods 简介

1.1 CocoaPods

• CocoaPods 是 macOS 和 iOS 下的一个第三类库管理工具，通过 CocoaPods 工具我们可以为项目添加被称为 “Pods” 的依赖库（这些类库必须是 CocoaPods 本身所支持的），并且可以轻松管理其版本。

• CocoaPods 的项目源码和依赖库在 Github 上管理。该项目开始于 2011 年 8 月 12 日，在这几年多的时间里，它持续保持活跃更新。

• 开发 iOS 项目不可避免地要使用第三方开源库，CocoaPods 的出现使得我们可以节省设置和更新第三方开源库的时间，在 iOS 开发中经常会用到第三方库如 AFNetworking，ASIHttpRequest 等，在使用第三方库时，你除了要导数源码外，但是，集成这些依赖库需要我们手动去配置，还有当这些第三方库发生了更新，还需要手动去更新项目。这就显得非常麻烦。有麻烦自然有解决办法，CocoaPods 就是为了解决这个问题而生的。通过 CocoaPods，我们可以将第三方的依赖库统一管理起来，配置和更新只需要通过简单的几行命令即可完成。

  • 在引入第三方库时它可以自动为我们完成各种各样的配置，包括配置编译阶段、连接器选项、甚至是 ARC 环境下的 -fno-objc-arc 配置等。

  • 使用 CocoaPods 可以很方便地查找新的第三方库，这些类库是比较“标准的”，而不是网上随便找到的，这样可以让我们找到真正好用的类库。

• CocoaPods 是用 ruby（一种面向对象的脚本语言）实现的，要想使用它首先需要有 ruby 的环境。幸运的是 macOS 系统默认已经可以运行 ruby 了。但是有时候 ruby 版本过低是无法正常支持 CocoaPods 的使用，所以需要先安装更新升级 rvm（安装和管理 ruby 的一种工具） 和 ruby。

2、CocoaPods 环境配置

2.1 检查更新 ruby 环境

• CocoaPods 是用 ruby（一种面向对象的脚本语言）实现的，要想使用它首先需要有 ruby 的环境。幸运的是 macOS 系统默认已经可以运行 ruby 了。但是有时候 ruby 版本过低是无法正常支持 CocoaPods 的使用，所以需要先安装更新升级 rvm（安装和管理 ruby 的一种工具） 和 ruby。

• 当 ruby 版本低于 v2.2.2 时，安装 CocoaPods 会报错。为防止 ruby 版本过低，建议先检查更新 ruby 环境，建议升级到 2.3.0 版本以上。

2.2 安装配置 CocoaPods

• 1）安装 CocoaPods

  • 在终端输入以下指令，安装 CocoaPods。

    # 安装 cocoapods 包，macOS EL Capitan 以下系统
    $ sudo gem install cocoapods
    

  • 安装过程中如果出现以下错误。

    ERROR: While executing gem ... (Errno::EPERM)
    Operation not permitted - /usr/bin/pod
    

  • 说明没有权限，需要使用以下指令安装。

    # 安装 cocoapods 包，macOS EL Capitan 及以上系统
    $ sudo gem install -n /usr/local/bin cocoapods
    

  • 安装成功后，输出如下。

    Successfully installed cocoapods-1.4.0
    Parsing documentation for cocoapods-1.4.0
    Done installing documentation for cocoapods after 12 seconds
    1 gem installed
    

  • 正常情况下此处会出现很大的坑，经常会出现各种报错问题，大多数是为 ruby 环境过低没有更新升级，或者是牵扯到 rvm 管理器环境的问题。

• 2）配置 CocoaPods

  • 所有的项目的 Podspec 文件都托管在 Github 的 Specs 上。第一次执行 pod setup 时，CocoaPods 会将这些 Podspec 索引文件更新到本地的 ~/.cocoapods/ 目录下，这个索引文件比较大，所以第一次更新时非常慢。

  • 安装完成后，执行以下命令，更新本地 podspec 索引文件仓库。

    # 更新本地 podspec 仓库
    $ pod setup
    

    • 等待较长一段时间后，输出以下信息即表明配置成功。

      Setting up CocoaPods master repo
        $ /usr/local/bin/git -C /Users/haiqianj/.cocoapods/repos/master fetch origin --progress
        remote: Counting objects: 74140, done.
        remote: Compressing objects: 100% (1399/1399), done.
        remote: Total 74140 (delta 24114), reused 23135 (delta 23131), pack-reused 49482
        Receiving objects: 100% (74140/74140), 7.98 MiB | 53.00 KiB/s, done.
        Resolving deltas: 100% (50830/50830), completed with 5027 local objects.
        From https://github.com/CocoaPods/Specs
           df292e26c73..ce7268fde74  master     -> origin/master
        $ /usr/local/bin/git -C /Users/haiqianj/.cocoapods/repos/master rev-parse --abbrev-ref HEAD
        master
        $ /usr/local/bin/git -C /Users/haiqianj/.cocoapods/repos/master reset --hard origin/master
        Checking out files: 100% (7847/7847), done.
        HEAD is now at ce7268fde74 [Add] TestUXsdk 0.1
      warning: inexact rename detection was skipped due to too many files.
      warning: you may want to set your diff.renameLimit variable to at least 7414 and retry the command.
      Setup completed
      

2.3 常用命令

• 1）rvm 常用命令

  # 查看 rvm 版本
  $ rvm -v
  
  # 查询已安装的 ruby
  $ rvm list
  
  # 查询已知的 ruby 环境
  $ rvm list known
  
  # 指定 ruby 版本进行更新
  $ rvm install 2.4.0
  
  # 卸载一个已安装 ruby 版本
  $ rvm remove 1.9.2
  

• 2）ruby 常用命令

  # 查看 ruby 版本
  $ ruby -v
  

• 3）gem 常用命令

  # 查看 rubygems 版本
  $ gem -v
  $ gem --version
  
  # 更新 rubygems 版本
  $ sudo gem update --system
  
  # 检查 ruby 源
  $ gem sources -l
  
  # 添加 ruby 源
  $ sudo gem sources -a https://gems.ruby-china.org/
  $ sudo gem sources --add https://gems.ruby-china.org/
  
  # 删除 ruby 源
  $ sudo gem sources -r https://rubygems.org/
  $ sudo gem sources --remove https://rubygems.org/
  
  # 清除过期的 gem
  $ gem cleanup
  
  # 安装 cocoapods 包
  $ sudo gem install cocoapods
  
  # 安装 cocoapods 包，macOS EL Capitan 及以上系统
  $ sudo gem install -n /usr/local/bin cocoapods
  
  # 删除 cocoapods 包
  $ gem uninstall cocoapods
  
  # 更新包
  $ gem update
  
  # 列出本地安装的包
  $ gem list
  

• 4）pod 常用命令

  # 更新本地 podspec 仓库
  $ pod setup    
  
  # 安装／下载第三方框架
  $ pod install
  
  # 更新第三方框架
  $ pod update
  
  # 列出本地 podspec 仓库所有可用的第三方框架
  $ pod list
  
  # 在本地 podspec 仓库中搜索名称为 query 的第三方框架
  # pod search [第三方框架名]
  $ pod search query
  
  # 更仔细的搜索，该命令不但搜索类库的名称，同时还搜索类库的描述文本，所以搜索速度也相对慢一些
  # pod search --full [第三方框架名]
  $ pod search --full query
  
  # 更新本地 podspec 仓库中第三方框架的索引文件
  # pod list 和 pod search 命令只搜索存在于本地 ~/.cocoapods 文件夹的所有第三方框架，
  # 并不会连接到远程服务器
  $ pod repo update master
  
  # 更新本地 podspec 仓库中第三方框架的索引文件，更新时显示详细信息
  $ pod repo update master --verbos
  
  # 注册 trunk
  # pod trunk register [邮箱地址] [用户名] --verbose
  $ pod trunk register EmailAddr userName --verbose
  
  # 向服务器查询自己的注册信息
  $ pod trunk me
  
  # 生成 podspec 文件
  # pod spec create [podspec 文件名]
  $ pod spec create query
  
  # 验证 podspec 文件是否合法
  # pod lib lint [podspec 文件名]
  $ pod lib lint query.podspec
  
  # 通过 trunk 推送 podspec 文件
  # pod trunk push [podspec 文件名]
  $ pod trunk push Name.podspec
  

  Usage:
  
    $ pod COMMAND
  
      CocoaPods, the Cocoa library package manager.
  
  Commands:
  
    + cache         Manipulate the CocoaPods cache
    + deintegrate   Deintegrate CocoaPods from your project
    + env           Display pod environment
    + init          Generate a Podfile for the current directory
    + install       Install project dependencies according to versions from a Podfile.lock
    + ipc           Inter-process communication
    + lib           Develop pods
    + list          List pods
    + outdated      Show outdated project dependencies
    + plugins       Show available CocoaPods plugins
    + repo          Manage spec-repositories
    + search        Search for pods
    + setup         Setup the CocoaPods environment
    + spec          Manage pod specs
    + trunk         Interact with the CocoaPods API (e.g. publishing new specs)
    + try           Try a Pod!
    + update        Update outdated project dependencies and create new Podfile.lock
  
  Options:
  
    --silent        Show nothing
    --version       Show the version of the tool
    --verbose       Show more debugging information
    --no-ansi       Show output without ANSI codes
    --help          Show help banner of specified comma
  

2.4 常见问题

• 1）问题 1

  • 问题描述

    Error fetching https://gems.ruby-china.org/:
    bad response Not Found 404 (https://gems.ruby-china.org/specs.4.8.gz)
    

  • 解决方案

    • 把安装流程中 $ gem sources -a https://gems.ruby-china.org/ 改为 $ gem sources -a https://gems.ruby-china.org/

• 2）问题 2

  • 问题描述

    ERROR: While executing gem ... (Errno::EPERM)
    Operation not permitted - /usr/bin/pod
    

  • 解决方案

    • 苹果系统升级 OS X EL Capitan 后会出现的插件错误，将安装流程中的 $ sudo gem install cocoapods 改为 sudo gem install -n /usr/local/bin cocoapods

• 3）问题 3

  • 问题描述

    ERROR:  Error installing cocoapods:
    activesupport requires Ruby version >= 2.2.2.
    

  • 解决方案

    • 输入 $ ruby -v 查看 ruby 版本：ruby 2.0.0p648 (2015-12-16 revision 53162) [universal.x86_64-darwin15]，版本过低，使用 RVM 对 Ruby 进行升级。

• 4）问题 4

  • 问题描述

    [!] Unable to satisfy the following requirements:
    - `AVOSCloud (~> 3.1.6.3)` required by `Podfile`
    
    Specs satisfying the `AVOSCloud (~> 3.1.6.3)` dependency were found,
    but they required a higher minimum deployment target.
    

  • 解决方案

    • 安装流程中的 Podfile 文件中 platform :ios, '6.0' 后边的 6.0 是平台版本号 ，一定要加上。

• 5）问题 5

  • 问题描述

    [!] The dependency `AFNetworking (~> 3.1.0)` is not used in any concrete target.
    

  • 解决方案

    • 百度上很多旧版本输入的类容：

      platform :ios, '8.0'
      pod 'AFNetworking', '~> 2.0'
      

    • 现在版本升级官方给的文档是：

      platform :ios, '8.0'
      
      target '项目名称' do
        pod 'AFNetworking', '~> 3.1.0'
      end
      

• 6）问题 6

  • 问题描述

    [!] Your Podfile has had smart quotes sanitised. To avoid issues
    in the future, you should not use TextEdit
    for editing it. If you are not using TextEdit, you should turn off
    smart quotes in your editor of choice.
    

  • 解决方案

    • 不要使用文本编辑去编辑 Podfile，使用 Xcode 编辑，或者使用终端敲命令去编辑。

• 7）问题 7

  • 问题描述

    /usr/local/bin/pod update
    env: ruby_executable_hooks: No such file or directory
    

    • 在 Xcode 的 CocoaPods 插件中使用 pod update 出现以上提示。

  • 解决方案

    • 在终端里输入 $ gem env 找到 SHELL PATH，修改 Xcode 的 cocoapods 插件里 GEM_PATH 选项为上面得到的路径，挨着试试总会成功的。

• 8）问题 8

  • 问题描述

    • 有一些库编译时候会有警告。但是作为一个有洁癖的人呢不想看见这些。

  • 解决方案

    • 可以在 platform :ios, ‘x.0’ 的后面加入这句，这样编译这些第三方库的时候就没有那些烦人的小警告了。

      inhibit_all_warnings!
      

• 9）问题 9

  • 问题描述

    • 有一个库 ReactiveCocoa。当关闭所有警告的时候。它就编译不过了。

  • 解决方案

    • 对他单独设置打开编译警告就好了。

      pod 'ReactiveCocoa', '~> 2.1.8', :inhibit_warnings => true
      

• 10）问题 10

  • 问题描述

    • 如果有多个 Targets 需要 pod 的库怎么办。

  • 解决方案

    • Podfile 的头部加入以下代码，AAAAA 和 BBBBB 都是你 target 的名字，这样不同的 target 都会有 pod 库了。主要是用来解决 Unit Test 需要 pod install 一些库的问题。

      link_with ['AAAAA', 'BBBBB']
      

• 11）问题 11

  • 问题描述

    [!] The `master` repo is not a git repo.
    

    • 原因：修改了 Xcode.app 的路径后，找不到 Xcode。

  • 解决方案

    • 终端执行即可

      sudo xcode-select -switch /Applications/Developer/Xcode.app（Xcode 实际路径）
      

• 12）问题 12

  • 问题描述

    [!] The specified path `QExtension.podspec` does not point to an existing podspec file.
    

    • 原因：没有进入到 .podspec 文件所在的文件夹

  • 解决方案

    • cd 进入到 .podspec 文件所在的文件夹

• 13）问题 13

  • 问题描述

    • 创建工程使用 cocoapods 时没有出现 xcworkspace 文件解决方法。

  • 解决方案

    /// 更新 cocoapods
    sudo gem install -n /usr/local/bin cocoapods
    
    /// 在工程目录下
    pod install
    

• 14）问题 14

  • 问题描述

    • Pod install 过程中遇到以下提示，该问题可能会导致找不到开源库头文件。

      - Use the `$(inherited)` flag, or
      - Remove the build settings from the target.
      

  • 解决方案

    All these 3 errors would be gone by adding $(inherited) to
    
      Header Search Paths
      Other Linker Flags
      Preprocessor Macros
    

    • 如上三处，查看一下是否加入了 $(inherited) 缺少的添加上，再 pod install 问题就可以解决。
• 1. 问题 15

  • 问题描述

    • Pod install 过程中遇到以下提示。

      [!] Smart quotes were detected and ignored in your Podfile. To avoid issues in the future, you should not use TextEdit for editing it. If you are not using TextEdit, you should turn off smart quotes in your editor of choice.

  • 解决方案

    • 不要使用文本编辑去编辑 Podfile，使用 Xcode 编辑，或者使用终端敲命令去编辑。

    • Using TextEdit will give you following

      pod ‘Parse’, ‘~> 1.7.1
      

      • 注意 引号

    • Use Xcode to open Podfile and you will get correct quotes as following

      pod 'Parse', '~> 1.7.1'
      

      • 注意 引号

    • Terminal Commands

      $ touch Podfile  //OR $ cd <parentDirectory of Podfile>
      $ open -a Xcode Podfile
      

3、CocoaPods 的使用

3.1 向 Xcode 工程中添加第三方库

• 1）新建工程，并在终端用 cd 指令打开到工程文件夹内。

• 2）搜索第三方框库

  • 在终端中输入以下指令，搜索需要添加的第三方库

    # 在本地 podspec 仓库中搜索第三方框库
    # pod search [第三方库名]
    $ pod search AFNetworking
    

    • 搜索结果如下

      -> AFNetworking (3.2.0)
         A delightful iOS and OS X networking framework.
         pod 'AFNetworking', '~> 3.2.0'
         - Homepage: https://github.com/AFNetworking/AFNetworking
         - Source:   https://github.com/AFNetworking/AFNetworking.git
         - Versions: 3.2.0, 3.1.0, 3.0.4, 3.0.3, 3.0.2, 3.0.1, 3.0.0, 3.0.0-beta.3, 3.0.0-beta.2,
         3.0.0-beta.1, 2.6.3, 2.6.2, 2.6.1, 2.6.0, 2.5.4, 2.5.3, 2.5.2, 2.5.1, 2.5.0, 2.4.1, 2.4.0, 2.3.1,
         2.3.0, 2.2.4, 2.2.3, 2.2.2, 2.2.1, 2.2.0, 2.1.0, 2.0.3, 2.0.2, 2.0.1, 2.0.0, 2.0.0-RC3, 2.0.0-RC2,
         2.0.0-RC1, 1.3.4, 1.3.3, 1.3.2, 1.3.1, 1.3.0, 1.2.1, 1.2.0, 1.1.0, 1.0.1, 1.0, 1.0RC3, 1.0RC2,
         1.0RC1, 0.10.1, 0.10.0, 0.9.2, 0.9.1, 0.9.0, 0.7.0, 0.5.1 [master repo]
         - Subspecs:
           - AFNetworking/Serialization (3.2.0)
           - AFNetworking/Security (3.2.0)
           - AFNetworking/Reachability (3.2.0)
           - AFNetworking/NSURLSession (3.2.0)
           - AFNetworking/UIKit (3.2.0)
      

• 3）添加配置文件

  • 在工程根目录下新建 Podfile 配置文件。

    # 创建并编辑 Podfile 文件
    $ vim Podfile
    

  • 按照以下格式，将上面搜索结果的第三行内容（即 pod 'AFNetworking', '~> 3.2.0'）输入到新创建的文件中。

    platform :ios, '8.0'               // 8.0 为添加的第三方库当前需支持的最低版本是 iOS 8.0
    
    target '项目名称' do                // 添加项目名称，新版本的需要加该句
    
      pod 'AFNetworking', '~> 3.1.0'   // 下载的 AFNetworking 版本是 3.1.0 及以上版本，
                                       // 直接写 pod 'AFNetworking' 代表下载最新版
    end
    

    platform :ios, '8.0'
    
    target 'Swift-Enum' do
    
      pod 'AFNetworking', '~> 3.1.0'
    end
    

    • 上面操作可以直接用下面的指令一步完成

      # echo -e "target '[项目名称]' do\npod '[第三方库名称]', '~> [第三方库版本]'\nend" > Podfile
      $ echo -e "target 'Swift-Enum' do\npod 'AFNetworking', '~> 3.1.0'\nend" > Podfile
      

    • 输入完毕后，保存退出。

• 4）下载第三方库

  • 配置文件 Podfile 设置好后，继续在终端中输入以下指令，下载配置添加的第三方库到项目中。

    # 安装／下载第三方框架
    $ pod install
    

    • 运行结果如下

      nalyzing dependencies
      Downloading dependencies
      Installing AFNetworking (3.1.0)
      Generating Pods project
      Integrating client project
      
      [!] Please close any current Xcode sessions and use `demoOC.xcworkspace` for this project from now on.
      Sending stats
      Pod installation complete! There is 1 dependency from the Podfile and 1 total pod installed.
      

    • 运行 pod install 命令后，之前添加的第三方库将会升级到最新版本，新添加的第三方库将会被下载添加到项目中。

• 5）打开工程

  • 下载完第三方库后，关闭所有的 Xcode 窗口，再次打开工程目录会看到多了一个后缀名为 .xcworkspace 文件，以后打开工程就双击这个文件打开了，而不再是打开 .xcodeproj 文件。

  • 进入工程后引入头文件不再是 #import "AFNetworking.h"，而是 #import <AFNetworking.h>

3.2 发布开源库到 CocoaPods 代码库中

• 发布流程

  

• 1）检查 trunk 信息

  • 在终端中输入以下指令，向服务器查询自己的 trunk 注册信息

    # 向服务器查询自己的注册信息
    $ pod trunk me
    

    • 如果输出如下信息，表示已经注册成功

      - Name:     QianChia
      - Email:    qianchia@icloud.com
      - Since:    July 17th, 06:26
      - Pods:
        - QConnectionDownloader
        - QFormData
        - QHashString
        - QSessionDownloader
        - QWebImage
      - Sessions:
        - July 17th, 06:26 - November 23rd, 01:33. IP: 43.225.238.143
      

  
    * 如果输出如下信息，表示需要注册
  
      ```
      [!] You need to register a session first.
      ```
  
  

• 2）注册 trunk 信息

  • 在注册 trunk 之前，需要确认当前的 CocoaPods 版本足够新，trunk 需要在 pod 0.33 以上版本，如果不满足参照 CocoaPods 环境配置章节更新。

  • 在终端中输入以下命令，注册 trunk 信息

    # 注册 trunk
    # pod trunk register [邮箱地址] [用户名] --verbose
    $ pod trunk register qianchia@icloud.com QianChia --verbose
    

    • 邮箱以及用户名请对号入座。

    • --verbose 参数是为了便于输出注册过程中的调试信息。

    • 执行上面的语句后，你的邮箱将会受到一封带有验证链接的邮件，如果没有请去垃圾箱找找，有可能被屏蔽了。点击邮件的链接就完成了 trunk 注册流程。

• 3）配置 PodSpec 文件

  • podspec 描述文件简单地讲就是让 CocoaPods 搜索引擎知道你的代码的作者、版本号、源代码地址、依赖库等信息的 ruby 类型文件。任何支持 CocoaPods 的开源代码都必须有 podspec 文件。CocoaPods 在 Github 中用一个 repo 来管理所有支持 CocoaPods 的开源代码。

  • 那如何编写 podspec 文件呢？官方提供了一个模板并附有非常详细的注释说明。

    • 在终端下，cd 到项目的根目录下，使用以下指令即可生成 podspec 文件模板。

      # 生成 podspec 文件
      # pod spec create [podspec 文件名]
      $ pod spec create Swift-Enum
      

      • 以上命令执行后在目录下会自动创建一个名为 Swift-Enum.podspec 的文件。

    • 建议直接拿一些成熟的开源库的 podspec 改就行，生成的模板里有很多冗余的属性。

• 4）推送 PodSpec 文件

  • 在推送 podspec 文件之前你需要确认以下两点，只有确保了这两点，CocoaPods 才能更准确地找到你的 repo。

    • 1> 确保你的源码已经 push 到 Github 上。
    • 2> 确保你所 push 的代码已经打上 "version tag"，也就是给源代码打上版本号标签。

  • 在 trunk 方式之前，我们一般用 pod lib lint 命令验证你的 podspec 文件是否合法。

    # 验证 podspec 文件是否合法
    # pod lib lint [podspec 文件名]
    $ pod lib lint Swift-Enum.podspec
    

  • 通过 trunk 上传你的 podspec 文件到 trunk 服务器。

    # 通过 trunk 推送 podspec 文件
    # pod trunk push [podspec 文件名]
    $ pod trunk push Swift-Enum.podspec
    

    • 执行上面的 push 操作，就相当于你把你的源代码提交给 CocoaPods 团队审核了，一般只需要几秒钟或者几分钟就可以完成了。podspec 文件被上传到了 trunk 服务器，其实最终也会自动添加到了 github 上的 CocoaPods/Specs 中。

  • 这里要注意一点，有时写的 podspec 文件在后面 push 的时候会提示 "The source_files pattern did not match any file." 错误，但是能用 pod lib lint 命令做本地校验时又是 OK 的。为什么呢？上述错误的意思是 pod 在网络上根据你指定的路径找不到相关文件。这时候你要核对网上 git 仓库的路径与 source_files（其他 _files 字段同理）要对应。*_files 字段指的是网络 git 上的路径。

  • 有时你可能会遇到这种情况：执行 pod trunk push 操作后发现 podspec 文件的某个地方写错了，想更新一下。对于这种情况，我们可能会先尝试着在把 podspec 文件 push 一次。但是如果你的代码版本号没变(podspec 里的 version 自然也没变)就会提示 push 失败，即使你更改了 podspec 的其他地方，pod 也会认为这两个文件是同一个。 目前为止找不到 trunk 的相关 update 接口，所以只能顺水推舟，更新源代码版本号（如：1.1.1->1.1.2），重新 push version tag，然后再执行 pod trunk push 操作。

• 5）更新本地 pod 依赖

  • 在 trunk podspec 文件后，先用 pod search 查找一下你的代码，有结果的话就欢天喜地；没有的话执行 pod setup 进行本地依赖库更新，再 search。