zzurang / ReactiveCocoa

Streams of values over time

ReactiveCocoa (RAC) is a Cocoa framework built on top of ReactiveSwift. It provides APIs for using ReactiveSwift with Apple's Cocoa frameworks.

1. Introduction
2. Example: online search
3. Objective-C and Swift
4. How does ReactiveCocoa relate to Rx?
5. Getting started

If you’re already familiar with functional reactive programming or what ReactiveCocoa is about, check out the Documentation folder for more in-depth information about how it all works. Then, dive straight into our documentation comments for learning more about individual APIs.

If you have a question, please see if any discussions in our GitHub issues or Stack Overflow have already answered it. If not, please feel free to file your own!

Compatibility

This documents the RAC 5 which targets Swift 3.0.x. For Swift 2.x support see RAC 4.

Introduction

ReactiveCocoa is inspired by functional reactive programming. Rather than using mutable variables which are replaced and modified in-place, RAC offers “event streams,” represented by the Signal and SignalProducer types, that send values over time.

Event streams unify all of Cocoa’s common patterns for asynchrony and event handling, including:

• Delegate methods
• Callback blocks
• NSNotifications
• Control actions and responder chain events
• Futures and promises
• Key-value observing (KVO)

Because all of these different mechanisms can be represented in the same way, it’s easy to declaratively chain and combine them together, with less spaghetti code and state to bridge the gap.

For more information about the concepts in ReactiveCocoa, see ReactiveSwift.

Objective-C and Swift

Although ReactiveCocoa was started as an Objective-C framework, as of version 3.0, all major feature development is concentrated on the Swift API.

RAC’s Objective-C API and Swift API are entirely separate, but there is a bridge to convert between the two. This is mostly meant as a compatibility layer for older ReactiveCocoa projects, or to use Cocoa extensions which haven’t been added to the Swift API yet.

The Objective-C API will continue to exist and be supported for the foreseeable future, but it won’t receive many improvements. For more information about using this API, please consult our legacy documentation.

We highly recommend that all new projects use the Swift API.

Getting started

ReactiveCocoa supports OS X 10.9+, iOS 8.0+, watchOS 2.0, and tvOS 9.0.

To add RAC to your application:

1. Add the ReactiveCocoa repository as a submodule of your application’s repository.
2. Run git submodule update --init --recursive from within the ReactiveCocoa folder.
3. Drag and drop ReactiveCocoa.xcodeproj, Carthage/Checkouts/ReactiveSwift/ReactiveSwift.xcodeproj, and Carthage/Checkouts/Result/Result.xcodeproj into your application’s Xcode project or workspace.
4. On the “General” tab of your application target’s settings, add ReactiveCocoa.framework, ReactiveSwift.framework, and Result.framework to the “Embedded Binaries” section.
5. If your application target does not contain Swift code at all, you should also set the EMBEDDED_CONTENT_CONTAINS_SWIFT build setting to “Yes”.

Or, if you’re using Carthage, simply add ReactiveCocoa to your Cartfile:

github "ReactiveCocoa/ReactiveCocoa"

Make sure to add ReactiveCocoa.framework, ReactiveSwift, and Result.framework to "Linked Frameworks and Libraries" and "copy-frameworks" Build Phases.

If you would prefer to use CocoaPods, there are some unofficial podspecs that have been generously contributed by third parties.

Once you’ve set up your project, check out the Framework Overview for a tour of ReactiveCocoa’s concepts, and the Basic Operators for some introductory examples of using it.