Jan172012

Creating a library to be shared between iOS and Mac OS X

By craig | January 17, 2012 | Posted in Tutorials | Tagged , | Comments off

One of the projects I am working on at the moment could possibly be deployed to the iPhone, iPad and Mac OS X. There is quite a chunk of behaviour that I would like to extract into a common library, and then just develop the UI for the respective platforms in their own projects. The project structure I have in mind is:

  • BDCommon – A shared library that contains logic that is common across all applications
  • MyMacApp – A Lion-based Mac application that depends on the BDCommon project
  • MyPhoneApp – A universal iOS application that depends on the BDCommon project

As you probably know, when it comes to linking libraries, iOS apps can only link static libraries and the preferred approach for Mac OS X apps is to use a framework. So, I decided to create a single project that has two targets:

  • BDCommon.framework (used when linking from a Mac OS X app)
  • libBDCommon.a (used when linking from an iOS app)

This post describes the steps I performed in Xcode4 to achieve this.

Create Common Project

What you are about to do is create a new MAC OS X Framework project called BDCommon. This will be the containing shell for both targets.

Create new Mac OS X Framework

Create a new Mac OS X Framework:

Create new project

Set the product name and company identifier:

Setting project properties

And save the project:

Save the project

Configure BDCommon Project

Now we need to configure our newly create BDCommon project to support having two targets (one for the framework and one for the static library). The default behaviour of Xcode4 is to use the target’s name as the product name. This is OK if you only have one target, but because we want to build two products that have the same “name” (ie. BDCommon.framework and libBDCommon.a) we have to have two targets, both with different names. Hence, we need to decouple the product’s name from the target’s name.

In build settings for the BDCommon target, change the Packaging/Product Name from $(TARGET_NAME) to BDCommon:

Change product name

We will now rename the name of the target itself to BDCommon.framework so that we can easily recognise it in the list of targets:

Change target name

One last thing is to rename the Scheme to BDCommon.Framework (like renaming the Target, this is mostly a cosmetic act that helps us distinguish between the framework’s scheme and the static library’s scheme:

Change scheme name

Perform a build. Confirm that the BDCommon.framework gets created:

Check framework has been built

Now would probably be a good time to commit your changes to git.

Adding the libBDCommon.a Static Library Target

So, we now have a project that contains a target that will build a framework for our Mac OS X apps. Next, we want to add an additional target to build a static library for our iOS apps.

Choose the File/New/New Target… menu option and add a Cocoa Touch Static Library:

Create new target

Set the name to BDCommon and add it to the BDCommon project:

Set static target name

Again, because we want to be able to rename the target, we need to decouple the product’s name by hard-coding it to BDCommon:

Change static product name

Let’s rename the target to libBDCommon.a so that it is more obvious which target is which:

Rename static target

And lastly, let’s rename the scheme to libBDCommon.a to match the target name (again, to make it easier to distinguish between the two targets’ schemes):

Rename static library scheme

Perform a build for both schemes (BDCommon.framework and libBDCommon.a). Here is where you will notice what I believe is a bug in Xcode4:

Static library not built

Despite Xcode4 reporting that the build was successful, libBDCommon.a is depicted in red (indicating that it hasn’t built successfully). If you choose Open in Finder for both products, you will notice that it can find where it built BDCommon.framework, but not where it built libBDCommon.a.

It turns that it has actually built libBDCommon.a – it just displays it in the wrong colour. Using Finder, you can navigate manually to the common build directory and see that they do indeed get built successfully:

Libraries being built

Almost done now. If you have a look at the files in your Project Navigator, you will notice that the BDCommon group is duplicated. This is due to Xcode4 being “helpful” and generating code when you added the second target. Note that it hasn’t actually generated two copies of the physical files… it has just created several references to the existing files. If you expand both BDCommon groups, you can delete the one with the fewer entries:

Extra BDCommon group

Make sure, though, that you choose Remove References Only though, otherwise, it will actually physically delete the files.

Deleting extra groups

When you deleted the references in the step above, you also would have removed the membership of those references for the physical files from the two targets. You need to make sure that both BDCommon.h is in the membership list of both framework and static library targets.

Target membership

The convention for shared libraries (whether they be a static library or a framework) is to have a single monolithic header file (in our case, that will be BDCommon.h) that imports all the other .h files. At the moment, we don’t have any other .h files to include, so go ahead and remove all content from BDCommon.h so that it is an empty file.

Make sure that BDCommon.h is declared as a public header for both targets:

Making headers public

You can safely remove BDCommon.m now, as it no longer serves any really purpose. Note that this time, you will really delete the file (not just the reference).

Perform another build for both schemes and make sure your products get rebuilt correctly.

Again, this would be a good time to check your code into git.

Adding Some Behaviour to the Common Project

Over time, I expect that my common project will evolve to contain many different classes. To illustrate the process for the purpose of this article, we’ll add a simple class called BDLog that has a single method that outputs Hello world. Clearly, this is a contrived example, but it should give an indication on how to add new functionality to your common library.

Add a new Objective-C class:

Create new BDLog class

Set the class name to be BDLog:

Setting class name to BDLog

And save to your BDCommon group. Make sure you included it in both the BDCommon.framework and the libBDCommon.a targets:

Saving new class dialog

Add a static method definition called log to BDLog.h:

+(void)log;

And a corresponding implementation in BDLog.m:

+(void)log {
	NSLog(@"Hello world!");
}

Now you need to declare it as a public header for both your targets so that it is accessible from the application projects:

Making headers public

Modify BDCommon.h to add the following line:

\#import <BDCommon/BDLog.h>

When building your libraries, Xcode4 copies the public headers for your static library into a directory like .../DerivedData-dflasdfiouknclskjdchvlawioiewhsk/Build/Products/Debug-iphonesimulator/usr/local/include. This is fine, but it means that you need to change the header search path for every project that wants to include it, which is a pain in the ass. What we can do to make this easier is to rely on a little bit of knowledge about the list of directories that Xcode automatically uses when building. As it turns out, it always adds a directory called include to the header search path. To take advantage of this, we will change the Packaging/Public Headers Folder Path from /usr/local/include to include/BDCommon (per the screenshot below, you can also use $(PRODUCT_NAME) which will automatically substitute BDCommon). Using this path, allows us to import our headers with a statement like #import <BDCommon/BDCommon.h>. This step is only required for the libBDCommon.a target.

Setting public header

Perform a build and check that both the framework and static libraries still build correctly.

Creating a Mac OS X Application

Alright, we are now at the moment of truth. We need to see whether all the hard work above (which should be a once-off setup) allows us to share common code. To do this, we’re first going to create a Mac OS X application and link to our framework.

Create a new Mac OS X app:

Create new Mac OS X app

Set the name to MyMacApp – although it doesn’t really matter… we are just verifying that the framework will link OK:

Setting Mac app name

And save the application:

Saving Mac OS X app

Open the Build Phases tab for your application, and expand the Link Binary with Libraries section:

Linking libraries

Click on the +, and with a bit of luck, our newly created framework should appear in the list of frameworks in the workspace. Select it, and choose Add:

Linking framework

Open up your App Delegate class implementation and add the following statement at the top of the file:

#import <BDCommon/BDCommon.h>

Now add the following code to the applicationDidFinishLaunching: method (if all goes well, Xcode4 will even auto-complete the class and method names for you):

[BDLog log];

Build and run. If everything goes to plan, you will see Hello world! appear in the console output.

Creating an iPhone Application

One down, one to go. Same basic deal as before – we are going to create an iPhone application, but this time we will link in the static library, instead of the framework.

Create a new iPhone app:

Creating iphone app

Set the name to MyPhoneApp:

Setting iphone app name

And save the application:

Saving iphone app

Open the Build Phases tab for your application, and expand the Link Binary with Libraries section:

iphone library links

Click on the +, and our newly created static library should appear in the list of libraries in the workspace. Select it, and choose Add:

iphone link static library

Open up your App Delegate class implementation and add the following statement at the top of the file:

#import <BDCommon/BDCommon.h>

Now add the following code to the application:didFinishLaunchingWithOptions: method (if all goes well, Xcode4 will even auto-complete the class and method names for you):

[BDLog log];

Build and run. If everything goes to plan, you will see Hello world! appear in the console output.

Linking Static Libraries That Contain Categories

If you use Objective-C categories in your common library, you will likely get an error when you link your static library against the iOS app. Apple has written an [article](http://developer.apple.com/library/mac/#qa/qa1490/_index.html “Building Objective-C static libraries with categories”) that describes the process to resolve this problem. In a nutshell, though, you can modify the *Other Linker Flags* in your iOS app to include the -ObjC and -all_load options:

Setting other linker flags

Wrapping Up

There are a few things that I haven’t yet touched on that I may include in a future post:

  • Bundling your library for distribution to other developers
  • Private header files

As this was my first foray into this topic, I would be very interested in hearing feedback from you. In particular, if there are pieces of the above that are incorrect or misleading, please let me know and I will correct ASAP.

Drop me a line at craig (at) blackdogfoundry (dot) com

By craig | Posted in Tutorials | Tagged , | Comments off
May272010

Using BlackDog Replication in your Application

By craig | May 27, 2010 | Posted in Tutorials | Tagged , , , , | Comments off

Overview

This service is designed to assist you in keeping your application reference (or operational) data up-to-date. For example, consider the case where you have developed an application that stores train timetable information in an sqlite database on your iphone. This information would be correct at the time of application publication, however, over time it would quickly become out of date. The replication service that BlackDog offers is to store a copy of the “master” data on the BlackDog server (which you can update at any time), and the devices connect to the BlackDog server and replicate down only the changed records.

Many developers write their own data replication behaviour, but it is complex and error-prone. The BlackDog Replication service allows you to concentrate on developing your application’s behaviour and core functionality, not dealing with challenges like replication.

This tutorial describes the steps you will need to perform in order to integrate the sqlite replication behaviour into your application. It assumes that you are have previously used XCode to develop iphone applications.

The overriding premise of the BlackDog replication behaviour is that you, as the application developer, can develop your application with only a small amount of consideration to the replication that occurs under the covers. This means that you should be able to develop your application reading from the database with no BlackDog functionality, and then add in the BlackDog replication once your application is working.

Looking at a typical iphone development project, it would normally involve the following high-level sequence of steps:

  • Create initial sqlite database that contains some data
  • Copy that database into your project’s resource folder
  • Build your application that reads from that database using sqlite APIs
  • Finalise the contents of the sqlite database
  • Perform final testing
  • Ship the application to Apple for approval

Contrast that to the workflow when using the BlackDog replication libraries (new steps in bold):

  • Create initial sqlite database that contains some data
  • Copy that database into your project’s resource folder
  • Build your application that reads from that database using sqlite APIs
  • Finalise the contents of the sqlite database
  • Upload the contents of the sqlite database to the BlackDog server
  • Add a few lines of code to invoke the BlackDog replication service
  • Perform final testing
  • Ship the application to Apple for approval

Downloading BlackDog Libraries

The first thing you will need to download is the latest BlackDog replication libraries. The BlackDog libraries come in a ZIP file that contains a number of libraries, but the two that you will need to use the replication functionality are:

  • bdcommon
  • bdrepl

When you unzip that file, you will find the following file hierarchy:

You will note that there are libraries provided for both Release and Debug compilation options, as well as the device and simulator runtime engines. The Headers directory contains the Objective-C header files that define the BlackDog functionality. Unzip this file into a directory of your choosing. For the purposes of this tutorial, I assume that the zip file was unzipped into /Users/xxxx/BlackDog

Setting up your XCode Environment

As all developers like to manage their development environment settings, there is no single canonical way to set up your environment. However, there are several key objectives that must be achieved to link in the BlackDog replication libraries.

  • Include the Headers directory
  • Link the replication libraries
  • Add some pre-requisite frameworks

One possible way of achieving each of these is described below.

Include the Headers directory

Right-click on your Target, and choose Get Info. On the Build tab, type “header search” in the filter field and enter /Users/xxxx/BlackDog/Headers into the “Header Search Paths” setting.

Link the replication libraries

In the Target Info Build tab, filter for “other linker flags” and enter -all_load -lbdcommon -lbdrepl in the “Other Linker Flags” setting.

In the Target Info Build tab, filter for “library search” and add /Users/xxxx/BlackDog/$(CONFIGURATION)$(EFFECTIVE_PLATFORM_NAME) in the “Library Search Paths” setting.

Note that the use of the $(CONFIGURATION) and $(EFFECTIVE_PLATFORM_NAME) variables are a clever technique that allows for dynamically picking up the correct BlackDog runtime library depending on whether you are running on the device or simulator, or in Debug/Release mode.

Add some pre-requisite frameworks

In the Target Info General tab, add the following frameworks/dynamic libraries:

  • CFNetwork.framework
  • libxml2.dylib
  • libsqlite3.0.dylib

Calling the Libraries

Once your XCode environment has been setup correctly, you can now start calling the Replication libraries. The functionality that is available is defined in the BlackDogReplication.h file in the Headers folder. The API is very simple:

@interface BlackDogReplication : NSObject {	
}
 
/**
 * Launches a synchronous replication.  If you require an asynchronous
 * invocation, use a separate background thread to run this function.
 * 
 * Parameters:
 *   delegate - The delegate that provides the input parameters and responds
 *              to the callback functions as replication occurs
 *   fullReplication - Should we get a full replication, or a delta.  In nearly
 *                     all cases, this value will be false as you would normally
 *                     only want to replicate changes since your last update.
 *                     However, there may be cases where you want to completely
 *                     refresh the contents of the table.  In those rare cases,
 *                     pass true in this parameter.
 */
+(void)replicate:(id<BlackDogReplicationDelegate>)delegate fullReplication:(BOOL)fullReplication;
@end

There is a single static method defined on the BlackDogReplication class that takes your delegate and a boolean indicating whether you want a full replication, or an incremental replication. You will nearly always want an incremental so you should pass NO as the parameter. You will need to define a delegate class that can be used, and it will need to implement the methods that are defined in the BlackDogReplicationDelegate class and its parent class (BlackDogDelegate). The simplest example of a delegate class looks like:

@implementation DemoDelegate
 
-(NSString *)appKey {
	return @"cd79fbe3ae6d41ba9daad1acf45b5bff";
}
-(NSString *)secretKey {
	return @"3a1248037bc74fd2aa512f4e8feabf90";
}
-(NSString *)sqliteDatabasePath {
	NSString *docDirectory = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) objectAtIndex:0];
	return [docDirectory stringByAppendingPathComponent:@"database.sqlite"];
}
-(NSString *)tableName {
	return @"mytable";
}
-(int)initialChangeId {
	return 1;
}
@end

An example invocation of the API looks like:

DemoDelegate *delegate = [[DemoDelegate alloc] init];
[BlackDogReplication replicate:delegate fullReplication:NO];
[delegate release];

The above code connects to the BlackDog server and replicates any changes since your device last replicated data from the master server.

Updating your data

There are two ways to update your master data:

  1. Uploading a complete sqlite database via the BlackDog website (non-incremental)
  2. Invoking a web service (XML-based) APIs to send incremental updates to the BlackDog server

Some important notes

  • When you initially upload an sqlite database to the BlackDog website, it performs a number of validations, and creates a snapshot of the data with a changeID of 1.
  • Every time changes get made to the table and uploaded to the BlackDog website, the changed records (including deletions) are flagged with the next ChangeID.
  • The client libraries know what the latest ChangeID is for the data on the device, so when it performs a replication, it only fetches the rows that have been changed since that ChangeID.
  • If your replicated tables do not make use of a primary key column, the BlackDog replication service is unable to provide incremental replication. That is, the whole table will be replicated even if only one row has changed.
  • If you delete a replicated table from the BlackDog server, the data is gone forever. You can upload a fresh copy of the table, but it will be given a ChangeID of 1 and your devices are very likely to have a ChangeID of, say, 23. In this case the client will download a complete set of the data again.

Caveats for uploading complete sqlite databases

  • If you upload a complete sqlite database via the website, it is treated as non-incremental. That is, when devices replicate they will receive a complete data refresh. If you need incremental changes to be incremented, you need to use the BlackDog web services which will be described in a later tutorial.
  • If the uploaded sqlite database contains multiple tables, all tables will be registered for replication (if there are tables in the database that you do not need for replication, you can delete the reference to them on the BlackDog website.) Tables that already exist on the BlackDog server will be updated with a new ChangeID; new tables will be initialised with a ChangeID of 1.
By craig | Posted in Tutorials | Tagged , , , , | Comments off
May272010

BlackDog Features

By craig | May 27, 2010 | Posted in Tutorials | Tagged , , , , , | Comments off

Registration

In order to use the BlackDog services, you first need to register for an account. To do this, you will need to select an account name, password and provide your email address.

Once you have entered the required details, you will be sent a confirmation email with a URL for you to click on to confirm your account.

Applications

Within your BlackDog account, you have the ability to define an application. The application name can be whatever you like (it is purely informational to help you manage your applications within BlackDog), and would typically align to an application that you submit to the Apple Store/Android Marketplace. If you have an application that runs on multiple devices (but still has the same underlying behaviour), you would only create one application in BlackDog.

Once you’ve created the application, it will be assigned an application key and a secret key. These values are used on the mobile devices to create secure sessions with the BlackDog server.

You can define multiple applications that all have completely separate functionality and settings.

Using APIs

The primary purpose of BlackDog is for you to take advantage of the iPhone and Android libraries and embed them in your mobile applications. Currently, the following libraries are provided:

  • bdrepl
  • bdnotify

The above libraries also depend on the bdcommon library for some base functionality. For example, if you are using the Replication API, you will need to include both bdcommon and bdrepl libraries.

The key input that you, as a developer, need to provide is defined by either the BlackDogReplicationDelegate or BlackDogNotificationDelegate protocol/interface. Both of these interfaces extend from a parent interface called BlackDogDelegate that defines some common behaviour.

iPhone

/**
 * The BlackDogDelegate protocol is designed to represent a common set of functions
 * across all BlackDog Foundry services.  In particular, by abstracting the application 
 * key and secret key into this protocol, it gives the developers the freedom to share
 * an implementation of this protocol across multiple BlackDog services (such as 
 * replication and analytics), without having to duplicate information.
 *
 * As a stand-alone protocol, this isn't a particularly useful class.  Delegates should
 * not implement this protocol directly, but rather implement one or more specific
 * protocols such as BlackDogReplicatorDelegate.
 */
@protocol BlackDogDelegate <NSObject>
 
/**
 * Returns a string containing your application's 32-character application key.  
 * eg. "2119cafdaa37402c9c0af77e8f701f58"
 */
-(NSString *)appKey;
 
/**
 * Returns a string containing your application's 32-character secret key.  
 * eg. "f333759829f74d4faf07496aeac23604"
 */
-(NSString *)secretKey;
 
@optional
 
/**
 * Called by the BlackDog libraries if a session with the BlackDog server is unable
 * to be established.   During typical operations, this should never be called, with 
 * the possible exception of when the BlackDog server is down (or for some reason 
 * temporarily not servicing requests), in which case, the code parameter will be 
 * STATUS_TEMPORARILY_UNAVAIL.  In this case, it may be meaningful to let end-users
 * know that there is a temporarily problem with replication (depending on how much
 * visibility the end-users have of replication).  In all other cases, though, the
 * code and reason parameters will be of little meaning to end-users - they are aimed
 * at the developer of the application.
 * 
 * Parameters:
 *   code   - Contains a integer code that gives a hint of what the problem may have been.   
 *   reason - Contains a (possibly) human-readable string with a little more info.
 */
-(void)didFailToEstablishSession:(int)code reason:(NSString *)reason;
 
/**
 * Called by the BlackDog libraries if a a particular API call was not successful.
 * Usually this would occur if the call to the remote service was technically sucessful
 * (ie. the remote service was invoked), but suffered an error during execution.  This
 * might be due to you passing invalid data, or perhaps due to a BlackDog server error
 * condition.  There is also a chance that the client-side BlackDog libraries had some
 * problems performing an action (for example, if errors were experienced opening a local
 * sqlite database.  The code and reason parameters will almost certainly contain no 
 * meaningful information that would be able to be displayed to end-users - they are 
 * aimed at the developer of the application.
 * 
 * Parameters:
 *   code   - Contains a integer code that gives a hint of what the problem may have been.   
 *   reason - Contains a (possibly) human-readable string with a little more info.
 */
-(void)didFailToInvokeRemoteService:(int)code reason:(NSString *)reason;
 
@end

If you are developing an application for the iPhone that is using the BlackDog replication services, you would define your delegate class like so (note that extremely minimal error handling methods have been implemented):

#import "DemoDelegate.h"
 
@implementation DemoDelegate
 
-(NSString *)appKey {
	return @"cd79fbe3ae6d41ba9daad1acf45b5bff";
}
-(NSString *)secretKey {
	return @"3a1248037bc74fd2aa512f4e8feabf90";
}
-(NSString *)sqliteDatabasePath {
	NSString *docDirectory = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) objectAtIndex:0];
	return [docDirectory stringByAppendingPathComponent:@"database.sqlite"];
}
-(NSString *)tableName {
	return @"mytable";
}
-(int)initialChangeId {
	return 1;
}
-(void)didFailToFetchChanges:(int)code reason:(NSString *)reason {
	NSLog(@"%@", reason);
}
-(void)didFailToEstablishSession:(int)code reason:(NSString *)reason {
	NSLog(@"%@", reason);
}
-(void)didFailToInvokeRemoteService:(int)code reason:(NSString *)reason {
	NSLog(@"%@", reason);
}
@end

If you were using both replication and notification, you have three choices:

  1. Define a single delegate class that implements both BlackDogReplicationDelegate and BlackDogNotificationDelegate.
  2. Define two separate delegate classes – one that implements BlackDogReplicationDelegate and one that implements BlackDogNotificationDelegate
  3. Define three delegate classes – one that implements BlackDogDelegate (eg. MyDelegate) and provides the common details (application and secret key), and two others that subclass MyDelegate that respectively implement the replication and notification delegates.

Reports

BlackDog offers a number of reports that help you understand the usage of the BlackDog services.

Device Type Report

This report displays a pie chart with the percentage breakdown of the various device types. The high level report displays a breakdown of the device types (iPhone, Android, etc), but the Include Sub-Types checkbox allows you to drill down into more specifics on the actual types (eg. iPhone 3GS, HTC Magic, etc).

The start and end dates filter the time period that you would like the report over; for this report, the referenced date is date on which the device irst connected to the BlackDog services). You can optionally run the report across all your applications, or just for a single application. By default, the data in the BlackDog database is stored in UTC format, however, you can override this choose an offset to run the report for.

Device Installation Report

This report displays a line chart that shows the number of devices that connect to the BlackDog service for the first time during that period. You can group the data points of report on an hourly, daily, monthly and yearly basis.

The start and end dates filter the time period that you would like the report over; for this report, the referenced date is the date on which the device first connected to the BlackDog services). You can optionally run the report across all your applications, or just for a single application. By default, the data in the BlackDog database is stored in UTC format, however, you can override this choose an offset to run the report for.

API Usage Counts Report

This report displays a line chart indicating the volume of the various BlackDog API calls. This report will give you an excellent view of the way that your application interacts with the BlackDog services.

The start and end dates filter the time period that you would like the report over. You can optionally run the report across all your applications, or just for a single application. By default, the data in the BlackDog database is stored in UTC format, however, you can override this choose an offset to run the report for.

Active Devices Report

This report displays the list of active devices during the given period (where “active” is defined as having some interaction with the BlackDog services).

The start and end dates filter the time period that you would like the report over. You can optionally run the report across all your applications, or just for a single application. By default, the data in the BlackDog database is stored in UTC format, however, you can override this choose an offset to run the report for.

By craig | Posted in Tutorials | Tagged , , , , , | Comments off