Adium

Creating Plugins

Creating Adium plugins isn't for the faint of heart, but it's not that hard. This guide provides an overview of the process for creating plugins compatible with Adium 1.4.3 using Xcode 4.2 on OS X Lion 10.7.2.

External References

Over the years a number of people have written various tutorials and guides for creating Adium plugins. However, because Adium's plugin interface changes continuously and Apple tends to "improve" Xcode in mysterious ways, the guides become out of date rather quickly. Nonetheless, they're listed here for the sake of reference, completeness, and to give credit for their contributions to this guide.

Step 1: Compile Adium

Building a plugin requires a copy of the Adium plugin framework, which is available in the Adium source tree. Start by following the instructions at GettingNewestAdiumSource to download and build Adium. Be sure to get the version of the source that matches the version of Adium that your plugin will be deployed for (eg. the stable branch if you're going to publish your plugin for others to use).

Step 2: Create an Xcode project

From the File menu, choose New and then New Project... (or use the ⇧⌘N shortcut). Then select Framework & Library under Mac OS X in the left side bar. Next, select Bundle from the panel on the right. Then click the Next button.

Set the Product Name to "MyFirstAdiumPlugin" and enter a reverse domain name in the Company Identifier box. We're using "im.adium" for this example, but you should use a domain that you own. Set the Framework drop down to Cocoa and click Next. Choose a directory to save your project to and click Create.

You should now see a new project window that already has the MyFirstAdiumPlugin target selected and the Info tab displayed. If not, select the project root from the Navigation Pane, select MyFirstAdiumPlugin from the Targets list, and then select the Info tab.

Next, change Principle Class to MyFirstAdiumPlugin. Then, set Bundle identifier to im.adium.${PRODUCT_NAME:rfc1034identifier} in case Xcode didn't do it automatically. Don't forget to substitute your own reverse domain in place of "im.adium". Set Bundle creator OS Type code to "AdIM" and check that Bundle OS Type code is "BNDL". Again, Xcode should have done this automatically, but it's good to check it now and avoid complications later.

Now we need to add a new property to the target to specify the earliest version of Adium that the plugin is compatible with. Generally this should be set as low as you can get away with, but to keep things simple we'll stick with version 1.4. To add the new key, select the last row and click the plus sign. This will add a row and display a drop down of known key names. The key we want isn't in the list so dismiss the drop down and manually change the key name to "AIMinimumAdiumVersionRequirement". Make sure Type is "String" and then set the value to "1.4".

Now, select the Build Settings tab. In the search bar type "wrapper", look for "Wrapper Extension" in the results and change its value to "AdiumPlugin" in the Target column. Type "installation" in the search bar, look for "Installation Directory" in the search results and change its value to "$(HOME)/Library/Application Support/Adium 2.0/PlugIns/" in the Target column.

Next, find the framework $(ADIUM)/build/Debug/AIUtilities.framework (where $(ADIUM) is the directory that you cloned the Adium source into) and drag it into the “Frameworks/Other Frameworks” folder in the Project Navigator pane. When prompted, check the “Copy items into destination group’s folder (if needed)” and select “Create groups for any added folders.”

Finally, edit the Precompiled Prefix Header (.pch) file for your target. You can search for 'pch' in the files list to find it quickly. Add:

	#import <Adium/AISharedAdium.h>
	#import <AIUtilities/AIStringUtilities.h>

to it, as shown. PCH file in Xcode

That's it. Your project is now configured properly.

Step 3: Write some code

Now you get to write the skeleton code for the plugin. This code won't do anything interesting other than allow your plugin to connect to Adium.

Choose File | New File… from the File menu (or use the ⌘N shortcut), then select Cocoa under Mac OS X in the left pane. Choose Objective-C class and click Next. Name the class "MyFirstAdiumPlugin"" and leave the subclass as "NSObject". Then click Next.

Accept the default location in the file dialog by clicking Create.

You should now see MyFirstAdiumPlugin.m open in the standard editor with the default code for an NSObject subclass.

Now, you'll need to "#import <Adium/AIPlugin.h>" and add the "<AIPlugin>" protocol to the MyFirstAdiumPlugin class in MyFirstAdiumPlugin.h. Make it look like this:

#import <Adium/AIPlugin.h>

@interface MyFirstAdiumPlugin : NSObject <AIPlugin>

@end

Then add the methods installPlugin and uninstallPlugin to MyFirstAdiumPlugin.m. Don't worry about adding any code to these methods. For this simple plugin the methods only need to exist so that Adium can call them. A plugin that actually does something would want to handle setup and teardown in these methods.

#import "MyFirstAdiumPlugin.h"

@implementation MyFirstAdiumPlugin

- (void) installPlugin
{
    
}

- (void) uninstallPlugin
{
    
}

@end

Step 4: Compile and Install

The moment of truth has arrived. Choose Build from the Product menu (or use ⌘B) and fix any errors that turn up. Once you get everything building cleanly, look in the Products folder in the Navigation Pane for MyFirstAdiumPlugin.AdiumPlugin. Right-click on it and select Show in Finder. Then double-click the file in the resulting Finder window. Adium should launch, if it isn't already running, and install the plugin. You'll then need to restart Adium.

Congratulations! You've created your first Adium Plugin.

Attachments (12)

Page last modified by wixardy, 4 years ago