The podspec format

Subspecs

Some libraries are big and encompass multiple modules. To avoid bloating clients it is possible to specify subspecs within pods. A subspec, in general, is a narrower specification that describes a single component of the parent specification.

For example lets consider the ShareKit pod. ShareKit has 12 sharers at the time of writing (Evernote, Facebook ... Vkontakte). To include the whole library it is just possible to specify dependency 'ShareKit' in a Podfile. On the hand if an application only wishes to include sharers for Facebook and Twitter it can just specify in its podfile:

dependency 'ShareKit/Facebook'
dependency 'ShareKit/Twitter'

It is also important to note that for convenience, a subspec inherits some attributes from its parent. For example source files, libraries and dependencies common to all the subspecs of a specification. CocoaPods is smart enough to resolve any issue related to duplicates... so in the end it just works.

If a specification doesn't want to inherit all its subspecs it can specify a preferred dependency:

Pod::Spec.new do |s|
  s.name = 'RestKit'
  s.preferred_dependency = 'JSON'
  ...

  s.subspec 'JSON' do |js|
    js.dependency 'RestKit/ObjectMapping/JSON'
    js.dependency 'RestKit/ObjectMapping/CoreData'
    js.dependency 'RestKit/UI'
  end

  s.subspec 'XML' do |xs|
  ...
  end
  ...
end

Top level attributes

Attributes that represent the unique features of pod and can't be specified by subspecs.

Attribute	Required	Description
name	yes	The name of the pod or of the subspec.
version	yes	The version of the pod (see Semver).
authors	yes	The email and the name of the authors of the library.
license	yes	The license type, optionally the file or the text can be specified.
homepage	yes	The homepage of the pod.
summary	yes	A short description.
description	no	An optional longer description.
documentation	no	Any additional option to pass to appledoc.
source	yes	The location from where the source should be retreived.
header_dir	no	The directory where to store the headers files so they don't break includes.
header_mappings_dir	no	If not provided the headers files are flattened. Otherwise if a directory is provided the folder structure is preserved from it.
prefix_header_contents	no	Any content to inject in the prefix header of the pod project.
prefix_header_file	no	A file to inject in the prefix header of the pod project.
requires_arc	no	If the Pod uses ARC.

Chained attributes

Attributes that are chained upstream with the value of the parent specs if any. For example if a specification includes some source_files any of its subspecs will include those source files in addition to their source files.

None of those attributes is strictly required, but a specification must at least have some of them.

Attribute	Description
source_files	The source files of the specification.
resources	A list of resources. These are copied into the target bundle with a build phase script.
preserve_paths	Any file that should not be cleaned (CocoaPods cleans all files by default).
exclude_header_search_paths	Headers that should not be visible to the Pods project.
frameworks	A list of frameworks that the client application needs to link against.
libraries	A list of libraries that the client application needs to link against.
xcconfig	Any flag to add to final xcconfig file.
compiler_flags	A list of compiler flags to pass for the files of the specification.
dependency	Any Pods that specification depends on.

All of these attributes support platform specific values.

s.osx.source_files = 'MySuperNSTableView.{h,m}'
s.ios.source_files = 'MySuperUITableView.{h,m}'

Platform attributes

If a specification supports iOS and OS X it possible to specify the deployment targets:

s.ios.deployment_target = '5.0'
s.osx.deployment_target = '10.7'
```

On the other hand, if a specification only supports a platform it can specify with one of the following alternatives:

s.platform = :ios, '5.0' s.platform = :ios

**Note**: A subspec can restrict the platform of the parent specification. In this case it will be inherited by the parent specification only if the target of the podfile supports it. 

## Aliases

Attribute  | Alias
---------  | -------------
authors    | author
resources  | resource
frameworks | framework
libraries  | library