Podspec Syntax Reference v1.16.1

namerequired

The name of the Pod.

Examples:

spec.name = 'AFNetworking'

versionrequired

The version of the Pod. CocoaPods follows semantic versioning.

Examples:

spec.version = '0.0.1'

swift_versions

The versions of Swift that the specification supports. A version of '4' will be treated as '4.0' by CocoaPods and not '4.1' or '4.2'.

Note The Swift compiler mostly accepts major versions and sometimes will honor minor versions. While CocoaPods allows specifying a minor or patch version it might not be honored fully by the Swift compiler.

Examples:

spec.swift_versions = ['3.0']

spec.swift_versions = ['3.0', '4.0', '4.2']

spec.swift_version = '3.0'

spec.swift_version = '3.0', '4.0'

cocoapods_version

The version of CocoaPods that the specification supports.

Examples:

spec.cocoapods_version = '>= 0.36'

authorsrequired

The name and email addresses of the library maintainers, not the Podspec maintainer.

Examples:

spec.author = 'Darth Vader'

spec.authors = 'Darth Vader', 'Wookiee'

spec.authors = { 'Darth Vader' => '[email protected]',
                 'Wookiee'     => '[email protected]' }

social_media_url

The URL for the social media contact of the Pod, CocoaPods web services can use this.

For example, the @CocoaPodsFeed notifications will include the Twitter handle (shortening the description) if the URL is relative to Twitter. This does not necessarily have to be a Twitter URL, but only those are included in the Twitter @CocoaPodsFeed notifications.

Examples:

spec.social_media_url = 'https://twitter.com/cocoapods'

spec.social_media_url = 'https://groups.google.com/forum/#!forum/cocoapods'

licenserequired

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. If a license file is specified, it either must be without a file extensions or be one of txt, md, or markdown.

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.

Examples:

spec.license = 'MIT'

spec.license = { :type => 'MIT', :file => 'MIT-LICENSE.txt' }

spec.license = { :type => 'MIT', :text => <<-LICENSE
                   Copyright 2012
                   Permission is granted to...
                 LICENSE
               }

Supported Keys:

:type

:file

:text

homepagerequired

The URL of the homepage of the Pod.

Examples:

spec.homepage = 'http://www.example.com'

readme

The URL for the README markdown file for this pod version.

Examples:

spec.readme = 'https://www.example.com/Pod-1.5-README.md'

changelog

The URL for the CHANGELOG markdown file for this pod version.

Examples:

spec.changelog = 'https://www.example.com/Pod-1.5-CHANGELOG.md'

sourcerequired

The location from where the library should be retrieved.

Examples:

Specifying a Git source with a tag. This is how most OSS Podspecs work.

spec.source = { :git => 'https://github.com/AFNetworking/AFNetworking.git',
                :tag => spec.version.to_s }

Using a tag prefixed with 'v' and submodules.

spec.source = { :git => 'https://github.com/typhoon-framework/Typhoon.git',
                :tag => "v#{spec.version}", :submodules => true }

Using Subversion with a tag.

spec.source = { :svn => 'http://svn.code.sf.net/p/polyclipping/code', :tag => '4.8.8' }

Using Mercurial with the same revision as the spec's semantic version string.

spec.source = { :hg => 'https://bitbucket.org/dcutting/hyperbek', :revision => "#{s.version}" }

Using HTTP to download a compressed file of the code. It supports zip, tgz, bz2, txz and tar.

spec.source = { :http => 'http://dev.wechatapp.com/download/sdk/WeChat_SDK_iOS_en.zip' }

Using HTTP to download a file using a hash to verify the download. It supports sha1 and sha256.

spec.source = { :http => 'http://dev.wechatapp.com/download/sdk/WeChat_SDK_iOS_en.zip',
                :sha1 => '7e21857fe11a511f472cfd7cfa2d979bd7ab7d96' }

Supported Keys:

:git => :tag, :branch, :commit, :submodules

:svn => :folder, :tag, :revision

:hg => :revision

:http => :flatten, :type, :sha256, :sha1, :headers

summaryrequired

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 capitalised and containing the correct punctuation.

Examples:

spec.summary = 'Computes the meaning of life.'

description

A description of the Pod more detailed than the summary.

Examples:

spec.description = <<-DESC
                     Computes the meaning of life.
                     Features:
                     1. Is self aware
                     ...
                     42. Likes candies.
                   DESC

screenshots

A list of URLs to images showcasing the Pod. Intended for UI oriented libraries. CocoaPods recommends the usage of the gif format.

Examples:

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' ]

documentation_url

An optional URL for the documentation of the Pod which will be honoured by CocoaPods web properties. Leaving it blank will default to a CocoaDocs generated URL for your library.

Examples:

spec.documentation_url = 'http://www.example.com/docs.html'

prepare_command

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. The working directory is the root of the Pod.

If the pod is installed with the :path option this command will not be executed.

Examples:

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

static_framework

Indicates, that if use_frameworks! is specified, the pod should include a static library framework.

Examples:

spec.static_framework = true

deprecated

Whether the library has been deprecated.

Examples:

spec.deprecated = true

deprecated_in_favor_of

The name of the Pod that this one has been deprecated in favor of.

Examples:

spec.deprecated_in_favor_of = 'NewMoreAwesomePod'

platform

The platform on which this Pod is supported. Leaving this blank means the Pod is supported on all platforms. When supporting multiple platforms you should use deployment_target below instead.

Examples:

spec.platform = :osx, '10.8'

spec.platform = :ios

spec.platform = :osx

deployment_target

The minimum deployment targets of the supported platforms.

As opposed to the platform attribute, the deployment_target attribute allows to specify multiple platforms on which this pod is supported — specifying a different deployment target for each.

Examples:

spec.ios.deployment_target = '6.0'

spec.osx.deployment_target = '10.8'

dependency

Any dependency on other Pods or to a ‘sub-specification’.

Dependencies can specify versions requirements. The use of the optimistic 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.

Examples:

spec.dependency 'AFNetworking', '~> 1.0'

spec.dependency 'AFNetworking', '~> 1.0', :configurations => ['Debug']

spec.dependency 'AFNetworking', '~> 1.0', :configurations => :debug

spec.dependency 'RestKit/CoreData', '~> 0.20.0'

spec.ios.dependency 'MBProgressHUD', '~> 0.5'

info_plistmulti-platform

Key-Value pairs to add to the generated Info.plist.

The values will be merged with the default values that CocoaPods generates, overriding any duplicates.

For library specs, the values will be merged into the generated Info.plist for libraries that are integrated using frameworks. It will have no effect for static libraries.

Subspecs (other than app and test specs) are not supported.

For app specs, the values will be merged into the application host's Info.plist.

For test specs, the values will be merged into the test bundle's Info.plist.

Examples:

spec.info_plist = {
  'CFBundleIdentifier' => 'com.myorg.MyLib',
  'MY_VAR' => 'SOME_VALUE'
}

requires_arcmulti-platform

requires_arc allows you to specify which source_files use ARC. This can either be the files which support ARC, or true to indicate all of the source_files use ARC.

Files which do not use ARC will have the -fno-objc-arc compiler flag.

The default value of this attribute is true.

Defaults to:

spec.requires_arc = true

Examples:

spec.requires_arc = false

spec.requires_arc = 'Classes/Arc'

spec.requires_arc = ['Classes/*ARC.m', 'Classes/ARC.mm']

frameworksmulti-platform

A list of system frameworks that the user’s target needs to link against.

Examples:

spec.ios.framework = 'CFNetwork'

spec.frameworks = 'QuartzCore', 'CoreData'

weak_frameworksmulti-platform

A list of frameworks that the user’s target needs to weakly link against.

Examples:

spec.weak_framework = 'Twitter'

spec.weak_frameworks = 'Twitter', 'SafariServices'

librariesmulti-platform

A list of system libraries that the user’s target (application) needs to link against.

Examples:

spec.ios.library = 'xml2'

spec.libraries = 'xml2', 'z'

compiler_flagsmulti-platform

A list of flags which should be passed to the compiler.

Examples:

spec.compiler_flags = '-DOS_OBJECT_USE_OBJC=0', '-Wno-format'

pod_target_xcconfigmulti-platform

Any flag to add to the final private pod target xcconfig file.

Examples:

spec.pod_target_xcconfig = { 'OTHER_LDFLAGS' => '-lObjC' }

user_target_xcconfigmulti-platform

Specifies flags to add to the final aggregate target xcconfig file, which propagates to non-overridden and inheriting build settings to the integrated user targets.

This attribute is not recommended as Pods should not pollute the build settings of the user project and this can cause conflicts.

Multiple definitions for build settings that take multiple values will be merged. The user is warned on conflicting definitions for custom build settings and build settings that take only one value.

Typically clang compiler flags or precompiler macro definitions go in here if they are required when importing the pod in the user target. Note that, this influences not only the compiler view of the public interface of your pod, but also all other integrated pods alongside to yours. You should always prefer pod_target_xcconfig, which can contain the same settings, but only influence the toolchain when compiling your pod target.

Examples:

spec.user_target_xcconfig = { 'MY_SUBSPEC' => 'YES' }

prefix_header_contentsmulti-platform

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.

Examples:

spec.prefix_header_contents = '#import <UIKit/UIKit.h>'

spec.prefix_header_contents = '#import <UIKit/UIKit.h>', '#import <Foundation/Foundation.h>'

prefix_header_filemulti-platform

A path to a prefix header file to inject in the prefix header of the pod project. false indicates that the default CocoaPods prefix header should not be generated. true is the default and indicates that the default CocoaPods prefix header should be generated.

The file path options is not recommended as Pods should not pollute the prefix header of other libraries or of the user project.

Examples:

spec.prefix_header_file = 'iphone/include/prefix.pch'

spec.prefix_header_file = false

module_name

The name to use for the framework / clang module which will be generated for this specification instead of the default (header_dir if set, otherwise the specification name).

Examples:

spec.module_name = 'Three20'

header_dirmulti-platform

The directory where to store the headers files so they don't break includes.

Examples:

spec.header_dir = 'Three20Core'

header_mappings_dirmulti-platform

A directory from where to preserve the folder structure for the headers files. If not provided the headers files are flattened.

Examples:

spec.header_mappings_dir = 'src/include'

script_phasesmulti-platform

This attribute allows to define a script phase to execute as part of compilation of the Pod. Unlike a prepare command, script phases execute as part of xcodebuild they can also utilize all environment variables that are set during compilation.

A Pod can provide multiple script phases to execute and they will be added in the order they were declared and after taking into consideration their execution position setting.

Note In order to provide visibility and awareness of the contents of all script phases, a warning will be presented to the user upon installing your pod if it includes any script phases.

Examples:

spec.script_phase = { :name => 'Hello World', :script => 'echo "Hello World"' }

spec.script_phase = { :name => 'Hello World', :script => 'echo "Hello World"', :execution_position => :before_compile }

spec.script_phase = { :name => 'Hello World', :script => 'puts "Hello World"', :shell_path => '/usr/bin/ruby' }

spec.script_phase = { :name => 'Hello World', :script => 'echo "Hello World"',
  :input_files => ['/path/to/input_file.txt'], :output_files => ['/path/to/output_file.txt']
}

spec.script_phase = { :name => 'Hello World', :script => 'echo "Hello World"',
  :input_file_lists => ['/path/to/input_files.xcfilelist'], :output_file_lists => ['/path/to/output_files.xcfilelist']
}

spec.script_phases = [
    { :name => 'Hello World', :script => 'echo "Hello World"' },
    { :name => 'Hello Ruby World', :script => 'puts "Hello World"', :shell_path => '/usr/bin/ruby' },
  ]

source_filesmulti-platform

The source files of the Pod.

Examples:

spec.source_files = 'Classes/**/*.{h,m}'

spec.source_files = 'Classes/**/*.{h,m}', 'More_Classes/**/*.{h,m}'

public_header_filesmulti-platform

A list of file patterns that should be used as public headers.

These patterns are matched against the source files to include headers that will be exposed to the user’s project and from which documentation will be generated. When the library is built, these headers will appear in the build directory. If no public headers are specified then all the headers in source_files are considered public.

Examples:

spec.public_header_files = 'Headers/Public/*.h'

project_header_filesmulti-platform

A list of file patterns that should be used to mark project 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. When the library is built, these headers will not appear in the build directory.

Examples:

spec.project_header_files = 'Headers/Project/*.h'

private_header_filesmulti-platform

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. When the library is built, these headers will appear in the build directory.

Header files that are not listed as neither public nor project or private will be treated as private, but in addition will not appear in the build directory at all.

Examples:

spec.private_header_files = 'Headers/Private/*.h'

vendored_frameworksmulti-platform

The paths of the framework bundles that come shipped with the Pod. Supports both .framework and .xcframework bundles. The frameworks will be made available to the Pod and to the consumers of the pod.

Examples:

spec.ios.vendored_frameworks = 'Frameworks/MyFramework.framework'

spec.vendored_frameworks = 'MyFramework.framework', 'TheirFramework.xcframework'

vendored_librariesmulti-platform

The paths of the libraries that come shipped with the Pod. The libraries will be available to the Pod and the consumers of the Pod.

Examples:

spec.ios.vendored_library = 'Libraries/libProj4.a'

spec.vendored_libraries = 'libProj4.a', 'libJavaScriptCore.a'

on_demand_resourcesmulti-platform

A hash of on demand resources that should be copied into the target bundle. Resources specified here will automatically become part of the resources build phase of the target this pod is integrated into.

If no category is specified then :download_on_demand is used as the default.

Tags specified by pods are always managed by CocoaPods. If a tag is renamed, changed or deleted then CocoaPods will update the tag within the targets the pod was integrated into. It is highly recommended not to share the same tags for your project as the ones used by the pods your project consumes.

Examples:

s.on_demand_resources = {
  'Tag1' => 'file1.png'
}

s.on_demand_resources = {
  'Tag1' => ['file1.png', 'file2.png']
}

s.on_demand_resources = {
  'Tag1' => { :paths => ['file1.png', 'file2.png'], :category => :download_on_demand }
}

s.on_demand_resources = {
  'Tag1' => { :paths => ['file1.png', 'file2.png'], :category => :initial_install }
}

resource_bundlesmulti-platform

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.

For building the Pod as a static library, 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 minimise the chance of name collisions.

To provide different resources per platform namespaced bundles must be used.

Examples:

spec.ios.resource_bundle = { 'MapBox' => 'MapView/Map/Resources/*.png' }

spec.resource_bundles = {
    'MapBox' => ['MapView/Map/Resources/*.png'],
    'MapBoxOtherResources' => ['MapView/Map/OtherResources/*.png']
  }

resourcesmulti-platform

A list of resources that should be copied into the target bundle.

For building the Pod as a static library, 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 optimised by Xcode.

Examples:

spec.resource = 'Resources/HockeySDK.bundle'

spec.resources = ['Images/*.png', 'Sounds/*']

exclude_filesmulti-platform

A list of file patterns that should be excluded from the other file patterns.

Examples:

spec.ios.exclude_files = 'Classes/osx'

spec.exclude_files = 'Classes/**/unused.{h,m}'

preserve_pathsmulti-platform

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.

Examples:

spec.preserve_path = 'IMPORTANT.txt'

spec.preserve_paths = 'Frameworks/*.framework'

module_mapmulti-platform

The module map file that should be used when this pod is integrated as a framework.

false indicates that the default CocoaPods modulemap file should not be generated.

true is the default and indicates that the default CocoaPods modulemap file should be generated.

By default, CocoaPods creates a module map file based upon the public headers in a specification.

Examples:

spec.module_map = 'source/module.modulemap'

spec.module_map = false

subspec

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 as 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.

Examples:

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

requires_app_hostmulti-platform

Whether a test specification requires an app host to run tests. This only applies to test specifications.

Examples:

test_spec.requires_app_host = true

app_host_namemulti-platform

The app specification to use as an app host, if necessary.

schememulti-platform

Specifies the scheme configuration to be used for this specification.

Examples:

spec.scheme = { :launch_arguments => ['Arg1'] }

spec.scheme = { :launch_arguments => ['Arg1', 'Arg2'], :environment_variables => { 'Key1' => 'Val1'} }

Supported Keys:

:launch_arguments

:environment_variables

:code_coverage

:parallelizable

:build_configurations

test_spec

Represents a test specification for the library. Here you can place all your tests for your podspec along with the test dependencies.

Examples:

Pod::Spec.new do |spec|
  spec.name = 'NSAttributedString+CCLFormat'

  spec.test_spec do |test_spec|
    test_spec.source_files = 'NSAttributedString+CCLFormatTests.m'
    test_spec.dependency 'Expecta'
  end
end

app_spec

Represents an app specification for the library. Here you can place all your app source files for your podspec along with the app dependencies.

Examples:

Pod::Spec.new do |spec|
  spec.name = 'NSAttributedString+CCLFormat'

  spec.app_spec do |app_spec|
    app_spec.source_files = 'NSAttributedString+CCLFormat.m'
    app_spec.dependency 'AFNetworking'
  end
end

default_subspecs

An array of subspecs names that should be used as preferred dependency. If not specified, a specification requires all of its subspecs as dependencies.

You may use the value :none to specify that none of the subspecs are required to compile this pod and that all subspecs are optional.

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).

Examples:

spec.default_subspec = 'Core'

spec.default_subspecs = 'Core', 'UI'

spec.default_subspecs = :none

ios

Provides support for specifying iOS attributes.

Examples:

spec.ios.source_files = 'Classes/ios/**/*.{h,m}'

osx

Provides support for specifying OS X attributes.

Examples:

spec.osx.source_files = 'Classes/osx/**/*.{h,m}'

macos

Provides support for specifying OS X attributes.

Examples:

spec.osx.source_files = 'Classes/osx/**/*.{h,m}'

tvos

Provides support for specifying tvOS attributes.

Examples:

spec.tvos.source_files = 'Classes/tvos/**/*.{h,m}'

visionos

Provides support for specifying visionOS attributes.

Examples:

spec.visionos.source_files = 'Classes/visionos/**/*.{h,m}'

watchos

Provides support for specifying watchOS attributes.

Examples:

spec.watchos.source_files = 'Classes/watchos/**/*.{h,m}'