-
Notifications
You must be signed in to change notification settings - Fork 2.1k
GettingStarted_iOS
Getting started using XMPPFramework on iOS
The project comes with a sample Xcode project demonstrating running XMPPFramework on iOS. You can find it in the Xcode/iPhoneXMPP folder. This is not designed to be a full fledged application. It simply serves to show the potential of the framework as well as providing a concrete example of using the code on the iOS platform. Feel free to play with the project, and browse the AppDelegate code. Keep in mind that this sample project only makes use of a small portion of available functionality.
When you're ready to add the XMPPFramework to your own iOS project, this page will provide detailed instructions. (You can also use the included iPhoneXMPP Xcode project as a reference.)
It's best to work step by step. Don't skip steps.
Use source control to checkout the latest version of the project. The default branch contains the latest stable version of the code.
(We are moving towards a more structured repository with tagging. But bear with us for now.)
The framework has several dependencies. You do NOT have to git clone them separately. They are all included when you clone XMPPFramework, within the Vendor folder. We are going to walk through each dependency step-by-step, ensuring your project complies at the end of each step.
The first dependency is CocoaLumberjack. This is the logging framework used throughout the project.
(More information about this logging framework can be found on the Intro to XMPPFramework page. Plus there is a ton of documentation available on Lumberjack's project page.)
(You don't need to separately clone CocoaLumberjack. It's included in the Vendor folder when you clone XMPPFramework.) Copy Vendor/CocoaLumberjack into your project, and add to your Xcode project.
Lumberjack doesn't have any sub-dependencies or special required frameworks.
Ensure your project compiles.
The second dependency is CocoaAsyncSocket. This is the low-level networking code used by the framework.
(You don't need to separately clone CocoaAsyncSocket. It's included in the Vendor folder when you clone XMPPFramework.) Copy Vendor/CocoaAsyncSocket into your project, and add to your Xcode project.
This dependency uses Manual Retain/Release, unlike the rest of the framework. (In Xcode 4, go to Target -> Build Phases -> Compile Sources, double-clic GCDAsyncSocket.m, and add -fno-objc-arc to the compiler flags)
This dependency requires you to add Apple's CFNetwork framework to your project. (In Xcode 4, go to Target -> Build Phases -> Link Binary With Libraries -> + -> Select CFNetwork from drop down list)
Ensure your project compiles.
The third dependency is KissXML. Since Apple did not include the NSXML classes in iOS (NSXMLDocument, NSXMLElement, NSXMLNode), we use KissXML as a drop in replacement.
(You don't need to separately clone KissXML. It's included in the Vendor folder when you clone XMPPFramework.) Copy Vendor/KissXML into your project, and add to your Xcode project.
KissXML uses libxml2 internally. Follow these detailed instructions (with pictures) explaining how to properly add libxml2 to your Xcode project. After you have done so, ensure your project compiles.
The fourth and final dependency is libidn. This library comes pre-installed on iOS. Add the following files to your project, and add to your Xcode project:
- Vendor/libidn/idn-int.h
- Vendor/libidn/stringprep.h
- Vendor/libidn/libidn.a
The last file listed above (libidn.a) is a static library, compiled as a fat binary including many architectures (x86*64, i386, ppc, armv6, armv7). As a result, it is a rather large file (1.3 MB). But fear not! The compiler will extract only those architectures it needs. Additionally it will extract only the portions of the library that get used, which in our case is only tiny portion of the entire library. In other words, this library won't add any significant size to your application!
Note: The source code for libidn is included in the project. (libidn-1.15.tar.gz) Obviously you should NOT add this to your project.
Ensure your project compiles.
Add the following folders to your project, and add to your Xcode project:
- Categories
- Core
- Utilities
In addition, add libresolv.dylib to your Xcode project. (In Xcode 4, go to Target -> Build Phases -> Link Binary With Libraries -> + -> Select libresolv.dylib from drop down list)
Ensure your project compiles.
And now you're ready to start using XMPPFramework in your project. The Intro to XMPPFramework page explains how to do this.
##Common Installation Problems
In XCode 4.2.1 (and perhaps other versions), following these directions will allow a bare bones project to compile. However, upon importing an XMPPFramework class, such as by calling '#import XMPP.h' will cause XCode to show an error 'XMPP.h' not found. It appears that XCode is not finding any of the XMPPFramework files.
The fix for this is to make sure that you DID NOT just drag and drop the XMPPFramework files into your project. Notice in this wiki is says to copy the files into your project folder, and then add the files into your project. So, if your XCode project is called XMPPTest, there will be an XMPPTest folder wherever you created your project, as in /Users/johndoe/XMPPTest. Taking step 2 for example, you need to press the "option" key and drag the folder titled "CocoaLumberjack" into /Users/johndoe/XMPPTest. THEN you can drag the "CocoaLumberjack" folder inside /Users/johndoe/XMPPTest into your actual XCode project. When you do, you should be sure to check the box "Copy items into destination's group folder (if needed) and select the radio button "Create folder references for any added folders". You should make sure that the checkboxes inside the "Add to targets" box are checked.
If you do not do this, XMPPFramework will not be functional.
Keep in mind that various optional extensions may have other requirements. For example, core data storage classes are obviously going to require the CoreData framework. If you add an optional extension to your project, and you get linker errors, then take a look at the various #imports in the header and implementation files within the extension that you added. If you see something like this:
#import <SystemConfiguration/SystemConfiguration.h>Then one can deduce that they'll need to add the SystemConfiguration framework to their project.
The latest versions of XMPPFramework use ARC. If you're not using ARC in your project, learn how to properly flag the XMPPFramework files as ARC in your Xcode project on the ARC page.
If you have questions concerning XMPPFramework, feel free to make use of the XMPPFramework Mailing List.