A specification describes a version of Pod library. It includes details about where the source should be fetched from, what files to use, the build settings to apply, and other general metadata such as its name, version, and description.
A stub specification file can be generated by the pod spec create command.
The specification DSL provides great flexibility and dynamism. Moreover, the DSL adopts the convention over configuration and thus it can be very simple:
Pod::Spec.new do |s|
s.name = 'Reachability'
s.version = '3.1.0'
s.license = h,m'
s.framework = 'SystemConfiguration'
s.requires_arc = true
end
A ‘root’ specification stores the information about the specific version of a library.
The attributes in this group can only be written to on the ‘root’ specification, not on the ‘sub-specifications’.
The attributes listed in this group are the only one which are required by a podspec.
The attributes of the other groups are offered to refine the podspec and follow a convention over configuration approach. A root specification can describe these attributes either directly of through ‘sub-specifications’.
A specification should indicate the platforms and the correspondent deployment targets on which the library is supported.
If not defined in a subspec the attributes of this group inherit the value of the parent.
In this group are listed the attributes related to the configuration of the build environment that should be used to build the library.
If not defined in a subspec the attributes of this group inherit the value of the parent.
These paths should be specified relative to the root of the source and may contain the following wildcard patterns:
Matches any file. Can be restricted by other values in the glob.
* will match all filesc* will match all files beginning with c*c will match all files ending with c*c* will match all files that have c in them (including at the
beginning or end)Equivalent to /.*/x in regexp.
Note this will not match Unix-like hidden files (dotfiles). In
order to include those in the match results, you must use something
like *,.*
Matches directories recursively.
Matches any one character. Equivalent to /. in regexp.1/
Matches any one character in set.
Behaves exactly like character sets in Regexp, including set negation
([^a-z]).
p,qMatches either literal p or literal q.
Matching literals may be more than one character in length. More than two literals may be specified.
Equivalent to pattern alternation in regexp.
Escapes the next meta-character.
Consider these to be evaluated in the source root of JSONKit.
"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"]
The specification class provides hooks which are called by CocoaPods when a Pod is installed.
A library can specify a dependency on either another library, a subspec of another library, or a subspec of itself.
A specification can store values which are specific to only one platform.
For example one might want to store resources which are specific to only iOS projects.
spec.resources = "Resources/**/*.png"
spec.ios.resources = "Resources_ios/**/*.png"
The name of the Pod.
spec.name = 'AFNetworking'
The version of the Pod. CocoaPods follows semantic versioning.
spec.version = '0.0.1'
The name and email address of each of the library’s the authors.
spec.author = 'Darth Vader'
spec.authors = 'Darth Vader', 'Wookiee'
spec.authors = { 'Darth Vader' => 'darthvader@darkside.com',
'Wookiee' => 'wookiee@aggrrttaaggrrt.com' }
The license of the Pod.
Unless the source contains a file named LICENSE.* or LICENCE.*,
the path of the license file or the integral text of the notice
commonly used for the license type must be specified.
This information is used by CocoaPods to generate acknowledgement files (markdown and plist) which can be used in the acknowledgements section of the final application.
spec.license = 'MIT'
spec.license = { :type => 'MIT', :file => 'MIT-LICENSE.txt' }
spec.license = { :type => 'MIT', :text => <<-LICENSE
Copyright 2012
Permission is granted to...
LICENSE
}
The URL of the homepage of the Pod.
spec.homepage = 'www.example.com'
The location from where the library should be retrieved.
Specifying a Git source with a tag.
spec.source = { :git => 'https://github.com/AFNetworking/AFNetworking.git',
:tag => 'v0.0.1' }
Using the version of the Pod to identify the Git tag.
spec.source = { :git => 'https://github.com/AFNetworking/AFNetworking.git',
:tag => "v#{spec.version}" }
A short (maximum 140 characters) description of the Pod.
The description should be short, yet informative. It represents the tag line of the Pod and there is no need to specify that a Pod is a library (they always are).
The summary is expected to be properly capitalized and containing the correct punctuation.
spec.summary = 'Computes the meaning of life.'
A description of the Pod more detailed than the summary.
spec.description = <<-DESC
Computes the meaning of life.
Features:
1. Is self aware
...
42. Likes candies.
DESC
A list of URLs to images showcasing the Pod. Intended for UI oriented libraries.
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" ]
A bash script that will be executed after the Pod is downloaded. This command can be used to create, delete and modify any file downloaded and will be ran before any paths for other file attributes of the specification are collected.
This command is executed before the Pod is cleaned and before the Pods project is created.
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
The platform on which this Pod is supported. Leaving this blank means the Pod is supported on all platforms.
spec.platform = :osx, "10.8"
spec.platform = :ios
spec.platform = :osx
The deployment targets of the supported platforms.
spec.ios.deployment_target = "6.0"
spec.osx.deployment_target = "10.8"
Any dependency on other Pods or to a ‘sub-specification’.
Dependencies can specify versions requirements. The use of the approximate
version indicator ~> is recommended because it provides good
control over the version without being too restrictive. For example,
~> 1.0.1 is equivalent to >= 1.0.1 combined with < 1.1. Similarly,
~> 1.0 will match 1.0, 1.0.1, 1.1, but will not upgrade to 2.0.
Pods with overly restrictive dependencies limit their compatibility with other Pods.
spec.dependency 'AFNetworking', '~> 1.0'
spec.dependency 'RestKit/CoreData', '~> 0.20.0'
spec.ios.dependency 'MBProgressHUD', '~> 0.5'
Wether the library requires ARC to be compiled. If true the
-fobjc-arc flag will be added to the compiler flags.
The default value of this attribute is transitioning from false
to true, and in the meanwhile this attribute is always required.
spec.requires_arc = true
A list of system frameworks that the user’s target needs to link against.
spec.ios.framework = 'CFNetwork'
spec.frameworks = 'QuartzCore', 'CoreData'
A list of frameworks that the user’s target needs to weakly link against.
spec.weak_framework = 'Twitter'
A list of libraries that the user’s target (application) needs to link against.
spec.ios.library = 'xml2'
spec.libraries = 'xml2', 'z'
A list of flags which should be passed to the compiler.
spec.compiler_flags = '-DOS_OBJECT_USE_OBJC=0', '-Wno-format'
Any flag to add to the final xcconfig file.
spec.xcconfig = { 'OTHER_LDFLAGS' => '-lObjC' }
Any content to inject in the prefix header of the pod project.
This attribute is not recommended as Pods should not pollute the prefix header of other libraries or of the user project.
spec.prefix_header_contents = '#import <UIKit/UIKit.h>'
spec.prefix_header_contents = '#import <UIKit/UIKit.h>', '#import <Foundation/Foundation.h>'
A path to a prefix header file to inject in the prefix header of the pod project.
This attribute is not recommended as Pods should not pollute the prefix header of other libraries or of the user project.
spec.prefix_header_file = 'iphone/include/prefix.pch'
The directory where to store the headers files so they don't break includes.
spec.header_dir = 'Three20Core'
A directory from where to preserve the folder structure for the headers files. If not provided the headers files are flattened.
spec.header_mappings_dir = 'src/include'
The source files of the Pod.
spec.source_files = "Classes/**/*.{h,m}"
spec.source_files = "Classes/**/*.{h,m}", "More_Classes/**/*.{h,m}"
A list of file patterns that should be used as public headers.
These are the headers that will be exposed to the user’s project and from which documentation will be generated. If no public headers are specified then all the headers are considered public.
spec.public_header_files = "Headers/Public/*.h"
A list of file patterns that should be used to mark private headers.
These patterns are matched against the public headers (or all the headers if no public headers have been specified) to exclude those headers which should not be exposed to the user project and which should not be used to generate the documentation.
spec.private_header_files = "Headers/Private/*.h"
The paths of the framework bundles that come shipped with the Pod.
spec.ios.vendored_frameworks = 'Frameworks/MyFramework.framework'
spec.vendored_frameworks = 'MyFramework.framework', 'TheirFramework.framework'
The paths of the libraries that come shipped with the Pod.
spec.ios.vendored_library = 'Libraries/libProj4.a'
spec.vendored_libraries = 'libProj4.a', 'libJavaScriptCore.a'
This attribute allows to define the name and the file of the resource bundles which should be built for the Pod. They are specified as a hash where the keys represent the name of the bundles and the values the file patterns that they should include.
We strongly recommend library developers to adopt resource bundles as there can be name collisions using the resources attribute.
The names of the bundles should at least include the name of the Pod to minimize the change of name collisions.
To provide different resources per platform namespaced bundles must be used.
spec.ios.resource_bundle = { 'MapBox' => 'MapView/Map/Resources/*.png' }
spec.resource_bundles = { 'MapBox' => ['MapView/Map/Resources/*.png'], 'OtherResources' => ['MapView/Map/OtherResources/*.png'] }
A list of resources that should be copied into the target bundle.
We strongly recommend library developers to adopt resource bundles as there can be name collisions using the resources attribute. Moreover resources specified with this attribute are copied directly to the client target and therefore they are not optimized by Xcode.
spec.resource = "Resources/HockeySDK.bundle"
spec.resources = ["Images/*.png", "Sounds/*"]
A list of file patterns that should be excluded from the other file patterns.
spec.ios.exclude_files = "Classes/osx"
spec.exclude_files = "Classes/**/unused.{h,m}"
Any file that should not be removed after being downloaded.
By default, CocoaPods removes all files that are not matched by any of the other file pattern.
spec.preserve_path = "IMPORTANT.txt"
spec.preserve_paths = "Frameworks/*.framework"
This is a convenience method which gets called after all pods have been downloaded but before they have been installed, and the Xcode project and related files have been generated. Note that this hook is called for each Pods library and only for installations where the Pod is installed.
This hook should be used to generate and modify the files of the Pod.
It receives the
Pod::Hooks::PodRepresentation
and the
Pod::Hooks::LibraryRepresentation
instances.
Override this to, for instance, to run any build script.
spec.pre_install do |pod, target_definition|
Dir.chdir(pod.root){ `sh make.sh` }
end
This is a convenience method which gets called after all pods have been downloaded, installed, and the Xcode project and related files have been generated. Note that this hook is called for each Pods library and only for installations where the Pod is installed.
To modify and generate files for the Pod the pre install hook should be used instead of this one.
It receives a
Pod::Hooks::LibraryRepresentation
instance for the current target.
Override this to, for instance, add to the prefix header.
spec.post_install do |library_representation|
prefix_header = library_representation.prefix_header_path
prefix_header.open('a') do |file|
file.puts('#ifdef __OBJC__\n#import "SSToolkitDefines.h"\n#endif')
end
end
Represents specification for a module of the library.
Subspecs participate on a dual hierarchy.
On one side, a specification automatically inherits as a dependency all it children ‘sub-specifications’ (unless a default subspec is specified).
On the other side, a ‘sub-specification’ inherits the value of the attributes of the parents so common values for attributes can be specified in the ancestors.
Although it sounds complicated in practice it means that subspecs in general do what you would expect:
pod 'ShareKit', '2.0'
Installs ShareKit with all the sharers like ShareKit/Evernote,
ShareKit/Facebook, etc, as they are defined a subspecs.
pod 'ShareKit/Twitter', '2.0'
pod 'ShareKit/Pinboard', '2.0'
Installs ShareKit with only the source files for ShareKit/Twitter,
ShareKit/Pinboard. Note that, in this case, the ‘sub-specifications’
to compile need the source files, the dependencies, and the other
attributes defined by the root specification. CocoaPods is smart enough
to handle any issues arising from duplicate attributes.
Subspecs with different source files.
subspec "Twitter" do |sp|
sp.source_files = "Classes/Twitter"
end
subspec "Pinboard" do |sp|
sp.source_files = "Classes/Pinboard"
end
Subspecs referencing dependencies to other subspecs.
Pod::Spec.new do |s|
s.name = 'RestKit'
s.subspec 'Core' do |cs|
cs.dependency 'RestKit/ObjectMapping'
cs.dependency 'RestKit/Network'
cs.dependency 'RestKit/CoreData'
end
s.subspec 'ObjectMapping' do |os|
end
end
Nested subspecs.
Pod::Spec.new do |s|
s.name = 'Root'
s.subspec 'Level_1' do |sp|
sp.subspec 'Level_2' do |ssp|
end
end
end
The name of the subspec that should be used as preferred dependency. If not specified a specifications requires all its subspecs as dependencies.
A Pod should make available the full library by default. Users can fine tune their dependencies, and exclude unneeded subspecs, once their requirements are known. Therefore, this attribute is rarely needed. It is intended to be used to select a default if there are ‘sub-specifications’ which provide alternative incompatible implementations, or to exclude modules rarely needed (especially if they trigger dependencies on other libraries).
spec.default_subspec = 'Pod/Core'
Provides support for specifying iOS attributes.
spec.ios.source_files = "Classes/ios/**/*.{h,m}"
Provides support for specifying OS X attributes.
spec.osx.source_files = "Classes/osx/**/*.{h,m}"