GettingStarted_Mac

Getting started using XMPPFramework on Mac OS X

Introduction

The project comes with a sample Xcode project demonstrating running XMPPFramework on Mac OS X. You can find it in the Xcode/DesktopXMPP 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 Mac OS X 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 project, this page will provide detailed instructions. (You can also use the included DesktopXMPP Xcode project as a reference.)

It's best to work step by step. Don't skip steps.

Step 1

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.)

Step 2

The framework has several dependencies. The dependencies are located within the Vendor folder (except one, libidn for MacOS, which is discussed below). 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.)

Copy Vendor/CocoaLumberjack into your project, and add to your Xcode project. In this step and each that follows, choose Create Groups for any added folders, which automatically adds the .m files to the targets you have selected.

Lumberjack doesn't have any sub-dependencies or special required frameworks. Ensure your project compiles.

Step 3

The second dependency is CocoaAsyncSocket. This is the low-level networking code used by the framework.

Copy Vendor/CocoaAsyncSocket into your project, and add to your Xcode project.

This dependency requires you to add Apple's Security framework to your project. (In Xcode 4, go to Target -> Build Phases -> Link Binary With Libraries -> + -> Select Security.framework from drop down list)

Ensure your project compiles.

Step 4

The third dependency is libxml2. This library comes pre-installed on Mac OS X (since 10.3). There are 2 steps to adding this to your project:

1. Tell Xcode where it can find the libxml2 header files so it will compile
2. Tell Xcode where it can find the libxml2 compiled library so it will link (last step of compiling)

You need to add the following to your compiler instructions:

• HEADER_SEARCH_PATHS = /usr/include/libxml2
• OTHER_LDFLAGS = -lxml2

Want detailed instructions on how to do this, with pictures? Keep reading.

Note: KissXML (Vendor/KissXML) is only required for iOS projects. Don't add it to desktop projects. However, the KissXML project has detailed instructions (with pictures) explaining how to properly add libxml2 to your Xcode project (as specified above). You can find these instructions here. Again, although libxml2 is required, KissXML is NOT.

Ensure your project compiles.

Step 5

The fourth and final dependency is libidn. 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.

Step 6

Add the following folders to your project, and add to your Xcode project:

• Authentication
• 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 page explains how to do this.

Extensions

The steps above outline how the steps and requirements to add the core framework files to your project. 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.

Automatic Reference Counting (ARC)

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.

Questions

If you have questions concerning XMPPFramework, feel free to make use of the XMPPFramework Mailing List.