Installation.md

Xcode 8.3, 9.x or 10.x / Swift 3 or 4

We recommend Carthage over CocoaPods, but both are supported installation methods.

CocoaPods

use_frameworks!
pod "PromiseKit", "~> 6.0"

Since CocoaPods 1.0 you will (probably) need to add the pod line to a target, eg:

use_frameworks!

target "Change Me!" do
  pod "PromiseKit", "~> 6.0"
end

Carthage

github "mxcl/PromiseKit" ~> 6.0

SwiftPM

package.dependencies.append(
    .Package(url: "https://github.com/mxcl/PromiseKit", majorVersion: 6)
)

Manually

You can just drop PromiseKit.xcodeproj into your project and then add PromiseKit.framework to your app’s embedded frameworks.

PromiseKit vs. Xcode

PromiseKit contains Swift, so there have been rev-lock issues with Xcode:

PromiseKit	Swift	Xcode	CI Status	Release Notes
6	3.1, 3.2, 3.3, 4.x	8.3, 9.x, 10.x		2018/02
5	3.1, 3.2, 3.3, 4.x	8.3, 9.x	Deprecated	n/a
4†	3.0, 3.1, 3.2, 3.3, 4.x	8.x, 9.x		2016/09
3	2.x	7.x, 8.0		2015/10
2	1.x	7.x	Deprecated	2015/10
1‡	N/A	*		–

† Probably supports Xcode 10 and Swift 4.2, if not, PR welcome.

‡ PromiseKit 1 is pure Objective-C and thus can be used with any Xcode, it is also your only choice if you need to support iOS 7 or below.

---

We also maintain a series of branches to aid migration for PromiseKit 2:

Xcode	Swift	PromiseKit	Branch	CI Status
8.0	2.3	2	swift-2.3-minimal-changes
7.3	2.2	2	swift-2.2-minimal-changes
7.2	2.2	2	swift-2.2-minimal-changes
7.1	2.1	2	swift-2.0-minimal-changes
7.0	2.0	2	swift-2.0-minimal-changes

We do not usually backport fixes to these branches, but pull-requests are welcome.

Xcode 8 / Swift 2.3 or Xcode 7

# CocoaPods
swift_version = "2.3"
pod "PromiseKit", "~> 3.5"

# Carthage
github "mxcl/PromiseKit" ~> 3.5

Using Git Submodules for PromiseKit’s Extensions

Please note, this is a more advanced technique

If you use CocoaPods and a few PromiseKit extensions then importing PromiseKit causes that module to import all the extension frameworks. Thus if you have an app and a few app-extensions (eg. iOS app, iOS watch extension, iOS Today extension) then all your final products that use PromiseKit will have forced dependencies on all the Apple frameworks that PromiseKit provides extensions for.

This isn’t that bad, but every framework that loads is overhead and startup time.

It’s better and worse with Carthage since we build individual micro-frameworks for each PromiseKit-extension, so at least all your final products only link against the Apple frameworks that they actually need. However, Apple have advised that apps only link against “about 12” frameworks for performance reasons, so for Carthage, we are worse off for this metric.

The solution is to instead only import CorePromise:

# CocoaPods
pod "PromiseKit/CorePromise"

# Carthage
github "mxcl/PromiseKit"
# ^^ for Carthage *only* have this

And to use the extensions you need via git submodules:

git submodule init
git submodule add https://github.com/PromiseKit/UIKit Submodules/PMKUIKit

Then in Xcode you can add these sources to your targets on a per-target basis.

Then when you pod update, ensure you also update your submodules:

pod update && git submodule update --recursive --remote

Release History

6.0 Feb 13th, 2018

• PromiseKit 6 announcement post.

4.0

• PromiseKit 4 announcement post.

3.0 Oct 1st, 2015

In Swift 2.0 catch and defer became reserved keywords mandating we rename our functions with these names. This forced a major semantic version change on PromiseKit and thus we took the opportunity to make other minor (source compatibility breaking) improvements.

Thus if you cannot afford to adapt to PromiseKit 3 but still want to use Xcode-7.0/Swift-2.0 we provide a minimal changes branch where catch and defer are renamed catch_ and defer_ and all other changes are the bare minimum to make PromiseKit 2 compile against Swift 2.

If you still are using Xcode 6 and Swift 1.2 then use PromiseKit 2.

2.0 May 14th, 2015

PromiseKit 2 announcement post.

1.5

Swift 1.2 support. Xcode 6.3 required.