CocoaPods 0.28

TL;DR: CocoaPods 0.28 introduces support for plugins.

Fighting feature creep in CocoaPods is not easy. We hear about a lot of great ideas and many of them don't make the cut as they would not be useful for at least 80% of our users. The ideal solution would be support for third-party plugins and, luckily, an elegant and lean patch from Les Hill has introduced it.

Plugin support allows one to tweak the internals of CocoaPods and to insert additional commands. As a matter of fact, two new commands are available right from the start:

The discoverability of plugins is another important topic that we considered. Our solution is to adopt a non-enforced convention: plugins should be named after the cocoapods-PLUGIN_NAME format. In this way, to check for the available plugins, you can just use this handy RubyGems search.

This release also includes a galore of bug fixes, mostly related to the handling of xcassets resources.

Creating plugins

A CocoaPods plugin is a gem which includes a file named cocoapods_plugin.rb. CocoaPods will load this file for any installed gem that includes it. The file will be loaded before running any command, but after CocoaPods’ files (and those of its dependencies) have been loaded. The convention is to use this file to require the actual implementation of the plugin.

For example cocoapods-open has the following cocoapods_plugin.rb:

require 'pod/command/open'

To create a new gem you can use bundler which provides a convenient command:

$ bundle gem NAME

Adding subcommands

Adding new subcommands is very easy. You just need to create a subclass of the command that will be used as the namespace. Subsequently, it is necessary to provide the metadata of the new command and its logic. For more information you can check the documentation of the CLAide gem and the source code of the CocoaPods commands.

If this sounds complicated, don’t be scared; we love simplicity! Actually the implementation of those steps is simpler than their description. Following you can find the complete implementation of the pod spec doc command.

# lib/pod/command/spec/doc.rb

module Pod
  class Command
    class Spec
      class Doc < Spec
        self.summary = "Opens the web documentation of a Pod."

        self.description = <<-DESC
          Opens the web documentation of the Pod with the given NAME.
        DESC

        self.arguments = 'NAME'

        def initialize(argv)
          @name = argv.shift_argument
          super
        end

        def validate!
          super
          help! "A Pod name is required." unless @name
        end

        def run
          path = get_path_of_spec(@name)
          spec = Specification.from_file(path)
          UI.puts "Opening #{spec.name} documentation"
          `open "http://cocoadocs.org/docsets/#{spec.name}"`
        end
      end
    end
  end
end

APIs

As of yet, an explicit API to access CocoaPods logic has not be defined. So try to fail as gracefully as possible in case a future version of CocoaPods breaks your usage. Also please let us know about your needs, so we can take them into account to finalize APIs.

Checklist

  • Name the plugin after the cocoapods-PLUGIN_NAME convention.
  • Include a cocoapods_plugin.rb file.
  • Use the cocoapods_plugin.rb file to load the actual implementation.
  • Fail gracefully when relying on CocoaPods methods.
  • Let us know if you make something cool!

Updating

To install the last release of CocoaPods you can run:

$ [sudo] gem install cocoapods

Until version 1.0 we strongly encourage you to keep CocoaPods up to date.

For all the details, don't miss the Changelog.