-
Notifications
You must be signed in to change notification settings - Fork 130
Adding libPusher to your project
There are a number of ways in which you can add libPusher to your project. This page documents how to get up and running with libPusher as quickly as possible.
First of all, you need to decide whether or not you want to use the latest version from source or download a pre-compiled static library (iOS) or framework (OSX). Downloading a pre-compiled library is the quickest way to get up and running, however depending on how you manage your project (e.g. if you use CocoaPods or git submodules) you may want to use one of the alternative methods below.
On the project Downloads page, you'll find a couple of different packages to download. Most people will want to grab the latest stable release, however there is also an automated nightly build if you want to run a bleeding-edge version.
Contained within each download package are a number of static libraries and a collection of header files. For more information, read the README file contained within the download.
Adding libPusher.framework to your OSX application is fairly straightforward. After dragging the downloaded framework into your project (don't forget to ask Xcode to copy the framework into your project), you'll need to ensure that the framework is linked to your app.
In your target's build settings, under Build Phases, expand "Link Binary With Libraries" and if the framework isn't already there, click the '+' button to add it.
Finally, you need to have Xcode copy the framework into your application bundle when it builds, so the framework can be found at runtime. To do this, still on the Build Phases tab, select "Add Build Phase" > "Add Copy Files".
Drag libPusher.framework from the project explorer into the new Copy Files build phase. Select "Frameworks" from the "Destination" menu and ensure "Copy only when installing" is not checked.
You should now be able to build and run your app.
Note: as of 18 September 2012, all nightly builds and any future release builds no longer include support for the armv6 architecture, and only include support for armv7 and armv7s (iPhone 5). If you require older device support, you will need to build the project yourself with your toolchain - the latest versions of Xcode and the iOS SDK do not include support for armv6.
Most people will want to use the combined fat static library. Simply copy libPusher-combined.a and the contents of the headers directory into your Xcode project and then:
-
Under the Build Phases tab for your target, expand "Link Binary With Libraries" and if libPusher-combined.a isn't there already, click the + symbol and add it.
-
Locate the "Other Linker Flags" build setting for your target and add
-all_load.
On both iOS and OSX, you will need to link against the following frameworks/libraries:
- libicucore.dylib
- CFNetwork.framework
- Security.framework
- SystemConfiguration.framework
You should now be able to build your project.
Important note: if you are using the pre-compiled static library and you are using the Reachability library in your project already, you will need to remove the implementation files for these libraries from your project as they are already compiled into the libPusher binaries. Leaving these files in your project will result in duplicate symbol errors from the linker. You should however leave the header files in your project in order to use them in your own source files.
CocoaPods is an Objective-C package manager; if you are familiar with the Rubygems eco-system, it is somewhere between Rubygems and Bundler - it allows you to manage all of your project dependencies using a simple manifest file. For more information on getting up and running with CocoaPods, you should read the documentation.
Assuming you do not have a Podfile in your project root already, go ahead and create one:
platform :ios
pod 'libPusher', '1.4'You can now use pod to install libPusher:
$ pod install
If this is the first time you've used CocoaPods for your project, an Xcode workspace containing your project and the Pods project will have been created. If you open this workspace file in Xcode, you should now be able to build your project - the Pods dependencies (including libPusher) will be compiled into a static library and linked to your own app/target.
Prior to 1.3, libPusher used the JSONKit library exclusively for JSON parsing. As of 1.3, it now uses the native NSJSONSerialization class to handle JSON parsing. As this class is only available on iOS 5 and OSX 10.7 and above, runtime support for JSONKit is maintained.
Because JSONKit is no longer bundled with libPusher, either as a CocoaPods dependency or embedded in the pre-compiled downloads, if you need to support older platforms, you must link JSONKit to your project yourself, either by adding the source directly to your project or by adding an explicit dependency to your Podfile if you are using CocoaPods.
Note: even if you have linked JSONKit, libPusher will still use NSJSONSerialization if it is available.
If you require a recent version of libPusher, you are advised to use the nightly build, available on the Downloads tab. If you would like to compile libPusher from source yourself, there are a few things you need to know.
First of all, libPusher itself uses CocoaPods to manage it's dependencies. You can view a list of it's dependencies by viewing the contents of the project's Podfile.
The project also contains a Rakefile and some Ruby scripts in Scripts for running various automated tasks and booting up a dummy authorisation server for testing presence and private channels with the bundled sample app. The Rakefile and these scripts rely on various Ruby gems to run and these gems are managed using Bundler. It is recommended that you use Ruby 1.9.x (MRI) to use these scripts. Run bundle install to install the necessary gems.
To build from Xcode, all you need to do is set up the CocoaPods dependencies as explained above, then open libPusher.xcworkspace. Make sure the libPusher scheme is selected and hit Build.
Having set up CocoaPods, you should be able to run build.sh. The script will do the following things:
- Run
bundle install - Update the project Pods by running
pod install - Run the
release:combinedRake task.
The release:combined Rake task will build libraries for the simulator and device and combine them into a single fat library using lipo. This is the same process that is used to build and deploy the nightly automated release.
To build and run the sample app, you'll need to create a Constants.h file containing your Pusher API key, app ID and secret key; see the sample application app delegate for instructions.