TweetFollow Us on Twitter

Dynamic Bundles Volume Number: 17 (2001)
Issue Number: 1
Column Tag: Mac OS X

Dynamic Bundles and Runtime Loading in OS X

By Andrew C. Stone

The Subtitle in Italics

As an application gets larger and more complex, the end user may perceive that the application loads slowly. Of course one can throw faster and multiple CPUs at the problem, but if you take advantage of dynamic bundle loading, your application can grow in functionality, but the time to launch remains lightning quick. How is this done? Simply by only loading the resources the user really needs at the moment. This article will show you how to architect your application to take advantage of bundles and late-loading.

Consider the fact that a typical application may have dozens of special panels and facilities that are occasionally accessed by the end user. There is no reason to load either the code or the resources for these panels until the end user actually requests that functionality.

There are many advantages to an application that dynamically loads bundles besides just fast launches. For example, in Stone Create, not only are all the inspectors, panels, and editors loaded on demand, but there is also a facility to load new tools at runtime. Any bundles found in the Tools directory are loaded and added to the tool palette when a new document is created. For example, the "Star" and "Embed" objects are loaded this way. New tools can be created and added without Create knowing anything about these in advance. By creating and adhering to protocols, which are sets of methods that must be implemented by an object, your application can deal with brand new objects at runtime.

The CFBundle, and its Cocoa cover class, NSBundle, handle all the details of locating and loading resources on demand. Most developers just use these for user interfaces, images, sounds and resource files, but it's simple to also load code on demand. The question then becomes, "how can I refer to code that is not yet loaded?" and "how can I compile code that has unresolved symbols"?

PreferencesController Bundle Example

One feature which makes OS X applications so powerful is the ease of user customization through the NSUserDefaults mechanism. Therefore, most applications require a user interface for preferences, but why load this panel and the code which controls it before it's absolutely needed if at all? We'll use the example of a preferences panel as a likely target for "bundling". The object "PreferenceController" is an NSWindowController subclass, which knows how to return a single instance of itself with a factory method, +sharedInstance:, because there is only one preferences panel in any application:

+ (id)sharedInstance {
    static PreferencesController *sharedPreferences = nil;

    // the first time through, we get the singleton preferences controller:
    if (!sharedPreferences) {
         sharedPreferences = [[PreferencesController                            allocWithZone:NULL] init];

    return sharedPreferences;

Our dynamic loading code will assume that every bundle responds to "+ sharedInstance" if there are only one of these objects (for example, there is only one Color panel per application).

If PreferenceController is linked into the application, you would have a method to bring up the panel in your application delegate object:

- (IBAction)showPreferencesPanelAction:(id)sender {
   [[PreferenceController sharedInstance] showWindow:self];

but then, that code would be loaded at the launch of the application, because it has to be compiled into the application's binary since it is referenced by name. The way we move to a dynamicly loaded model is to never refer to this class, except in a string as an argument to our dyamic loading method sharedInstanceOfClassName:, which appears later in the article:

    [[self sharedInstanceOfClassName:@"PreferencesController"] showWindow:self];

Now, the code will compile without including the PreferencesController class. Our job is to be sure it gets loaded when first needed. Typically, I add the bundle loading code to the NSApplication's delegate, which can be globally accessed with:

[NSApp delegate]

Another strategy, and a topic of a later article, is to use categories, and add that functionality right to the NSBundle class. I prefer using the NSApp's delegate because you can add cover methods for loading panels in a single class, and then connect menu items to the instantiated application delegate in the application's main NIB file. So, in this example, we would:

  1. add a method to the NSApp delegate class:
    - (IBAction)showPreferencesPanelAction:(id)sender;
  2. In InterfaceBuilder, connect the menu item "Preferences..." to the app delegate target, with the action "showPreferencesPanelAction:". You can quickly add actions to IB by dragging in the .h or .m file from ProjectBuilder into the document window of your nib. This is equivalent to "Classes->Read File...".
  3. When that menu item gets triggered, the application delegate will load the needed code. Subsequent invocations of the panel will be even swifter, but loading a single panel and controller code is pretty fast anyway.

Bundle Integration in Project Builder

From a Project Builder standpoint, your application's project becomes an aggregate of targets: the application target, and a target for each of the dynamically loaded bundles. Your application should add the product of each bundle to the Copy Files phase in the "Files and Build Phases" tab of the application target inspector.

Figure 1. Copy files phase adds bundles to the application target.

For backwards compatibility with OpenStep, I use the "Resources" directory to store bundles. The following code assumes that you are putting your bundles into the Resources subdirectory in <YOUR_APP_NAME>.app/Contents/. You change where they are copied to with the "Where:" pop-up in the Files & Build Phases pane of the Target Inspector. It is probably more intuitive to place bundles in "Bundles" subdirectory, and if you do, change the pathForResource:ofType: call to pathForBundle:ofType: in the method -(id)instanceOfClassName:(NSString *)name shared:(BOOL)shared.

Before looking at the very simple dynamic loading code, there is one point to consider. A Cocoa bundle has the notion of a principal class. That is the class that is both the owner of the NIB file, and the class that needs to be accessed first when the bundle is loaded. Many times, a bundle will only have one class in it, but its a potential gotcha to not specify the principal class if there are more than one class in the bundle. You assign the principal class in Project Builder - click the bundle target to load the target inspector. Select the "Bundle Settings" tab, and under the "Cocoa Specific" settings, type in the name of the class in the Principal class field, in this example, PreferencesController. Other fields let you assign version information, help files, main nib files, but these are optional.

The Dynamic Loading Code

The code offers two types of dynamic code loading - both singleton class instances such as the PreferencesController with sharedInstanceOfClassName, as well as simple new instances for each invocation with instanceOfClassName. Both use the same core code with a "shared" flag:

- (id)sharedInstanceOfClassName:(NSString *)name
    return [self instanceOfClassName:name shared:YES];

- (id)instanceOfClassName:(NSString *)name {
   return [self instanceOfClassName:name shared:NO];

instanceOfClassName would be used, for example, in a document-based architecture application where each document had its own version of that bundle's nib. An example would be a sheet that gets run on a per-document basis - because more than one document can be in a sheet-modal state at the same time. In this case, the document becomes responsible for freeing the bundle resources upon closing. Singleton instances are not freed until the application quits.

- (id)instanceOfClassName:(NSString *)name shared:(BOOL)shared
    id obj = nil;
    // NSBundle does the work of finding the bundle
    // pathForResource means "look into Resources folder"
    // use pathForBundle if you store them in the "Bundles" folder
    NSString *path = [[NSBundle mainBundle] 
                              pathForResource:name ofType:@"bundle"];
    if (path) {
        NSBundle *b = [[NSBundle allocWithZone:NULL] 

        // the object we wish to return is an instance of the principal class:
        if ((b != nil) && ([b principalClass] !=NULL)) {

      // we either grab the sharedInstance or create a new one:
      if (shared) obj = [[b principalClass] sharedInstance];
      else obj = [[[b principalClass] allocWithZone:NULL] init];

    // provide Developer feedback if something has gone wrong:
        }  else NSLog(@"Can't Load %@!\n", path);
    } else NSLog(@"Couldn't find %@ bundle!\n",name);

    return obj;


When designing your application, it is good practice to decompose your functionality into small, loadable pieces. By using dynamically loaded bundles, you gain launch speed and can take advantage of runtime binding for loading new tools. Probably most importantly, bundles create a firm foundation for future feature growth without application bloat as well as provide a natural modularity that is easy to comprehend.

Andrew Stone <> is CEO of and has been working with Cocoa since 1989 with its introduction as NeXTStep.


Community Search:
MacTech Search:

Software Updates via MacUpdate

OmniPlan 3.0 - Robust project management...
With OmniPlan, you can create logical, manageable project plans with Gantt charts, schedules, summaries, milestones, and critical paths. Break down the tasks needed to make your project a success,... Read more
Yummy FTP 1.11 - FTP/SFTP/FTPS client fo...
Yummy FTP is an FTP + SFTP + FTPS file transfer client which focuses on speed, reliability and productivity. Whether you need to transfer a few files or a few thousand, schedule automatic backups, or... Read more
Tweetbot 2.1 - Popular Twitter client. (...
Tweetbot is a full-featured OS X Twitter client with a lot of personality. Whether it's the meticulously-crafted interface, sounds and animation, or features like multiple timelines and column views... Read more
MacPilot 8.0 - Enable over 1,200 hidden...
MacPilot gives you the power of UNIX and the simplicity of Macintosh, which means a phenomenal amount of untapped power in your hands! Use MacPilot to unlock over 1,200 features, and access them all... Read more
Typinator 6.7 - Speedy and reliable text...
Typinator turbo-charges your typing productivity. Type a little. Typinator does the rest. We've all faced projects that require repetitive typing tasks. With Typinator, you can store commonly used... Read more
Adobe Lightroom 6.2 - Import, develop, a...
Adobe Lightroom is available as part of Adobe Creative Cloud for as little as $9.99/month bundled with Photoshop CC as part of the photography package. Lightroom 6 is also available for purchase as a... Read more
ForeverSave 2.1.4 - Universal auto-save...
ForeverSave auto-saves all documents you're working on while simultaneously doing backup versioning in the background. Lost data can be quickly restored at any time. Losing data, caused by... Read more
VueScan 9.5.27 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
AirPort Utility 6.3.6 - Set up and manag...
Note: Most recent release available only within OS X 10.11 El Capitan update. Use AirPort Utility to set up and manage your Wi-Fi network and AirPort base stations, including AirPort Express, AirPort... Read more
Quicksilver 1.3.1 - Application launcher...
Quicksilver is a light, fast and free Mac application that gives you the power to control your Mac with keystrokes alone. Quicksilver allows you to find what you need quickly and easily, then act... Read more

Super Sharp (Games)
Super Sharp 1.1 Device: iOS Universal Category: Games Price: $1.99, Version: 1.1 (iTunes) Description: Your finger has never been so sharp! Cut with skill to complete the 120 ingenious physics levels of Super Sharp and become a cut... | Read more »
Assembly - Graphic design for everyone...
Assembly - Graphic design for everyone 1.0 Device: iOS Universal Category: Photography Price: $2.99, Version: 1.0 (iTunes) Description: Assembly is the easiest most powerful design tool on the App Store. Create anything you can... | Read more »
YAMGUN (Games)
YAMGUN 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: The invasion has begun! Protect the walls of the citadel against waves of enemies! But watch out, you will soon run out of ammo...... | Read more »
Royal Bounty HD (Games)
Royal Bounty HD 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: New World Computing Approved "Hi Guys! looks good so far! keep up the good work. I worked on HoMM 3 and 4 creating all of the... | Read more »
Swords & Crossbones: An Epic Pirate...
Swords & Crossbones: An Epic Pirate Story 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: | Read more »
Camel Up (Games)
Camel Up 1.0.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.0 (iTunes) Description: | Read more »
The Martian: Bring Him Home (Games)
The Martian: Bring Him Home 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Based on the best selling novel and critically acclaimed film, THE MARTIAN tells the story of Astronaut Mark... | Read more »
This Week at 148Apps: September 21-30, 2...
Leap Into Fall With 148Apps How do you know what apps are worth your time and money? Just look to the review team at 148Apps. We sort through the chaos and find the apps you're looking for. The ones we love become Editor’s Choice, standing out above... | Read more »
Tweetbot 4 for Twitter (Social Networki...
Tweetbot 4 for Twitter 4.0 Device: iOS Universal Category: Social Networking Price: $4.99, Version: 4.0 (iTunes) Description: *** 50% off for a limited time. *** | Read more »
Mori (Games)
Mori 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Stop, rewind and unwind with Mori. Time is always running, take a moment to take control. Mori is an action puzzle game about infinitely... | Read more »

Price Scanner via

Save up to $350 with Apple refurbished iMacs
Apple has Certified Refurbished iMacs available for up to $350 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 27″ 3.5GHz 5K iMac – $1949 $350 off MSRP - 27... Read more
Mac Pros on sale for up to $300 off MSRP
B&H Photo has Mac Pros on sale for up to $300 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.7GHz 4-core Mac Pro: $2818.99, $181 off MSRP - 3.5GHz 6-core Mac Pro: $3699... Read more
5K iMacs on sale for up to $150 off MSRP, fre...
B&H Photo has the 27″ 3.3GHz 5K iMac on sale for $1899.99 including free shipping plus NY tax only. Their price is $100 off MSRP. They have the 27″ 3.5GHz 5K iMac on sale for $2149, $150 off MSRP... Read more
Twelve South Redesigns BookArc For Today’s Sm...
Twelve South has announced a redesigned version of their very first product, BookArc for MacBook. Tailored specifically for the newest generation of MacBooks, BookArc holds the new, smaller Apple... Read more
Phone 6s Tips & Tricks – Tips Book For iP...
Poole, United Kingdom based Tap Guides Ltd. has announced the release and immediate availability of iPhone 6s Tips & Tricks, an in-depth eBook available in the iBookstore that’s priced just $2.99... Read more
13-inch 2.5GHz MacBook Pro on sale for $994,...
Best Buy has the 13″ 2.5GHz MacBook Pro available for $994.99 on their online store. Choose free shipping or free instant local store pickup (if available). Their price is $105 off MSRP. Price valid... Read more
Is The iPad Pro Really A Serious Laptop Repla...
Probably not, at least for productive professionals and other power users. Steve Jobs declared that we’d entered the “post-PC Era” with the advent of the original iPad in 2010, a phrase we don’t hear... Read more
Wednesday Deal: 13-inch Retina MacBook Pros f...
Adorama has 13″ Retina MacBook Pros on sale for up to $130 off MSRP. Shipping is free, and Adorama charges sales tax for NY & NJ residents only: - 13″ 2.7GHz/128GB Retina MacBook Pro: $1199.99 $... Read more
uBar 3.0 for Mac OS X – Custom Dock Replaceme...
Brawer Software has announced the release of uBar 3.0, an important update to their popular app and window manager for Mac OS X. uBar allows users to position it whichever side of the screen they... Read more
13-inch 2.5GHz MacBook Pro (refurbished) avai...
Apple has Certified Refurbished 13″ 2.5GHz MacBook Pros available for $829, or $270 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.5GHz MacBook Pros... Read more

Jobs Board

*Apple* Retail - Multiple Customer Support P...
Job Description:Customer SupportSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the Read more
Software Engineer, *Apple* Watch - Apple (U...
…the team that is revolutionizing the watch! As a software engineer on the Apple Watch team, you will be responsible for building world-class applications and frameworks Read more
*Apple* Online Store UAT Lead - Apple (Unite...
**Job Summary** The Apple Online Store is a fast paced and ever evolving business environment. The User Acceptance Testing (UAT) lead in this organization is able to Read more
Hardware Systems Integration Engineer - *App...
**Job Summary** We are seeking an enthusiastic electrical engineer for the Apple Watch team. This is a design engineering position that entails working with Read more
Touch Validation Design (EE) - *Apple* Watc...
**Job Summary** Help launch next-generation Touch Technologies in Apple products. The Touch Technology team develops cutting-edge Touch solutions and technologies that Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.