PromiseKit Deployment and Usage Guide

Prerequisites

Swift 5.0+ (PromiseKit 8 requires recent Xcode versions, 13+)
macOS, iOS, tvOS, watchOS, or Linux (PromiseKit supports all these platforms)
Xcode (for iOS/macOS development) or Swift toolchain (for Linux)
CocoaPods (recommended for iOS/macOS) or Carthage/Accio/SwiftPM (alternatives)

Installation

Using CocoaPods (Recommended for iOS/macOS)

Install CocoaPods if not already installed:
```
sudo gem install cocoapods
```

Create a Podfile in your project directory:

use_frameworks!

target "YourTargetName" do
  pod "PromiseKit", "~> 8"
end

Install the pod:
```
pod install
```
Open the generated .xcworkspace file in Xcode.

Using Carthage

Create a Cartfile:
```
github "mxcl/PromiseKit" ~> 8
```
Install dependencies:
```
carthage update --platform iOS
```
Drag the built framework from Carthage/Build into your Xcode project.

Using Swift Package Manager

Add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/mxcl/PromiseKit.git", from: "8.0.0")
]

Add the package to your target dependencies.

Configuration

PromiseKit requires no special configuration files or API keys. However:

Optional Extensions: PromiseKit provides extensions for Apple's APIs. To use them, add the appropriate subspecs to your Podfile:

pod "PromiseKit/MapKit"          # For MKDirections().calculate().then { /*…*/ }
pod "PromiseKit/CoreLocation"    # For CLLocationManager.requestLocation().then { /*…*/ }

Foundation Extensions: The default CocoaPod includes extensions for Foundation and UIKit.
No Extensions: If you don't want any extensions:
```
pod "PromiseKit/CorePromise", "~> 8"
```

Build & Run

iOS/macOS Development

Open your project in Xcode:
```
open YourProject.xcworkspace
```
Build and run:
- Press Cmd + R to run on a simulator or device
- Press Cmd + B to build

Testing

PromiseKit includes comprehensive test suites. To run tests:

# For iOS/macOS
xcodebuild test -workspace YourProject.xcworkspace -scheme YourScheme -destination 'platform=iOS Simulator,name=iPhone 14'

# For Linux
swift test

Deployment

iOS/macOS Apps

App Store: Build your app normally and submit through Xcode's Organizer.
Enterprise Distribution: Use Xcode's archive and export features.
Ad Hoc: Use Xcode's archive and export features with ad hoc provisioning.

Swift Packages

Publish to Swift Package Index by hosting your package on GitHub.
Use SwiftPM for dependency management in other Swift projects.

Linux/Server-Side Swift

Deploy to any Linux server that supports Swift.
Use Docker containers for consistent deployment environments.

Troubleshooting

Common Issues

"PromiseKit/CorePromise" not found
- Ensure you've run pod install and opened the .xcworkspace file, not .xcodeproj.
- Check your Podfile syntax.
Swift version compatibility
- PromiseKit 8 requires Xcode 13+. For older Xcode versions, use PromiseKit 6, 5, or 4.
- Check the Installation Guide for version-specific instructions.
Build errors with extensions
- Some extensions may conflict with other libraries. Try using only PromiseKit/CorePromise if you encounter issues.
Linux compilation issues
- PromiseKit supports Linux, but some extensions may not be available. Check the CI Matrix for supported configurations.

Debugging

Use PromiseKit's built-in error handling with .catch { error in } blocks.
Check the Troubleshooting Guide for common compile errors and solutions.

Performance

PromiseKit is designed for performance. If you experience issues, check your promise chains for unnecessary nesting.
Use .ensure { } for cleanup code that should always execute.

Migration

For migrating from older PromiseKit versions, see the API Reference and Frequently Asked Questions.

How to Deploy & Use mxcl/PromiseKit