Class

Bundle

An NSBundle object helps you access the code and resources in a bundle directory on disk. Apple uses bundles to represent apps, frameworks, plug-ins, and many other specific types of content. Bundles organize their contained resources into well-defined subdirectories, and bundle structures vary depending on the platform and the type of the bundle. By using a bundle object, you do not have to know the structure of a bundle to access its resources. The bundle object provides a single interface for locating items, taking into account the bundle structure, user preferences, available localizations, and other relevant factors.

Overview

Any executable can use a bundle object to locate resources. You use an NSBundle object whenever you need to locate resources, either inside an app’s bundle or in a known bundle located elsewhere. You do not use a bundle object to locate files in a container directory or in other parts of the file system.

The general pattern for using a bundle object is as follows:

  1. Create a bundle object for the intended bundle directory.

  2. Use the methods of the bundle object to locate or load the needed resource.

  3. Use other system APIs to interact with the resource.

Some types of frequently used resources can be located and opened without a bundle. When loading images, store your images in asset catalogs and load them using the init(named:) methods of UIImage or NSImage. For string resources, use the NSLocalizedString family of macros to load individual strings instead of loading the entire .strings file yourself.

Finding and Opening a Bundle

Before you can locate a resource, you must first specify the bundle containing that resource. The NSBundle class has many methods for creating bundle objects, but the one you use most often is the main() method. The main bundle represents the bundle directory that contains the currently executing code. So for an app, the main bundle object gives you access to the resources that shipped with your app.

If your app interacts directly with plug-ins, frameworks, or other bundled content, you can use other methods of this class to create appropriate bundle objects. You can always create bundle objects from a known URL or path, but there are other methods that make it easier to access bundles your app is already using. For example, if you link to a framework, you can use the init(for:) method to locate the framework bundle based on a class defined in that framework.

// Get the app's main bundle
let mainBundle = NSBundle.mainBundle()
 
// Get the bundle containing the specified private class.
let myBundle = NSBundle.init(forClass: NSClassFromString("MyPrivateClass")!)

Locating Resources in a Bundle

You use an NSBundle object to obtain the location of specific resources inside the bundle. When looking for resources, you provide the name of the resource and its type at a minimum. For resources in a specific subdirectory, you can also specify that directory. After locating the resource, the bundle routines return a path string or URL that you can use to open the file.

Bundle objects follow a specific search pattern when looking for resources on disk. Global resources—that is, resources not in a language-specific .lproj directory—are returned first, followed by region- and language-specific resources. This search pattern means that the bundle looks for resources in the following order:

  1. Global (nonlocalized) resources

  2. Region-specific localized resources (based on the user’s region preferences)

  3. Language-specific localized resources (based on the user’s language preferences)

  4. Development language resources (as specified by the CFBundleDevelopmentRegion key in the bundle’s Info.plist file)

Because global resources take precedence over language-specific resources, you should never include both a global and localized version of a given resource in your app. When a global version of a resource exists, language-specific versions are never returned. The reason for this precedence is performance. If localized resources were searched first, the bundle object might waste time searching for a nonexistent localized resource before returning the global resource.

When locating resource files, the bundle object automatically considers many standard filename modifiers when determining which file to return. Resources may be tagged for a specific device (~iphone, ~ipad) or for a specific screen resolution (@2x, @3x). Do not include these modifiers when specifying the name of the resource you want. The bundle object selects the file that is most appropriate for the underlying device.

Understanding Bundle Structures

Bundle structures vary depending on the target platform and the type of bundle you are building. The NSBundle class hides this underlying structure in most (but not all) cases. Many of the methods you use to load resources from a bundle automatically locate the appropriate starting directory and look for resources in known places. You can also use the methods and properties of this class to get the location of known bundle directories and to retrieve resources specifically from those directories.

For information about the bundle structure of iOS and macOS apps, see Bundle Programming Guide. For information about the structure of framework bundles, see Framework Programming Guide. For information about the structure of macOS plug-ins, see Code Loading Programming Topics.

Symbols

Creating and Initializing a Bundle

init(for: AnyClass)

Returns the NSBundle object with which the specified class is associated.

init?(identifier: String)

Returns the NSBundle instance that has the specified bundle identifier.

init?(url: URL)

Returns an NSBundle object initialized to correspond to the specified file URL.

init?(path: String)

Returns an NSBundle object initialized to correspond to the specified directory.

Loading Nib Files

func loadNibNamed(String, owner: Any?, options: [AnyHashable : Any]? = nil)

Unarchives the contents of a nib file located in the receiver's bundle.

func loadNibNamed(String, owner: Any?, topLevelObjects: AutoreleasingUnsafeMutablePointer<NSArray>?)

Loads a nib from the bundle with the specified file name and owner.

Finding Resource Files

func url(forResource: String?, withExtension: String?, subdirectory: String?)

Returns the file URL for the resource file identified by the specified name and extension and residing in a given bundle directory.

func url(forResource: String?, withExtension: String?)

Returns the file URL for the resource identified by the specified name and file extension.

func urls(forResourcesWithExtension: String?, subdirectory: String?)

Returns an array of file URLs for all resources identified by the specified file extension and located in the specified bundle subdirectory.

func url(forResource: String?, withExtension: String?, subdirectory: String?, localization: String?)

Returns the file URL for the resource identified by the specified name and file extension, located in the specified bundle subdirectory, and limited to global resources and those associated with the specified localization.

func urls(forResourcesWithExtension: String?, subdirectory: String?, localization: String?)

Returns an array containing the file URLs for all bundle resources having the specified filename extension, residing in the specified resource subdirectory, and limited to global resources and those associated with the specified localization.

class func url(forResource: String?, withExtension: String?, subdirectory: String?, in: URL)

Creates and returns a file URL for the resource with the specified name and extension in the specified bundle.

class func urls(forResourcesWithExtension: String?, subdirectory: String?, in: URL)

Returns an array containing the file URLs for all bundle resources having the specified filename extension, residing in the specified resource subdirectory, within the specified bundle.

func path(forResource: String?, ofType: String?)

Returns the full pathname for the resource identified by the specified name and file extension.

func path(forResource: String?, ofType: String?, inDirectory: String?)

Returns the full pathname for the resource identified by the specified name and file extension and located in the specified bundle subdirectory.

func path(forResource: String?, ofType: String?, inDirectory: String?, forLocalization: String?)

Returns the full pathname for the resource identified by the specified name and file extension, located in the specified bundle subdirectory, and limited to global resources and those associated with the specified localization.

func paths(forResourcesOfType: String?, inDirectory: String?)

Returns an array containing the pathnames for all bundle resources having the specified filename extension and residing in the resource subdirectory.

func paths(forResourcesOfType: String?, inDirectory: String?, forLocalization: String?)

Returns an array containing the file for all bundle resources having the specified filename extension, residing in the specified resource subdirectory, and limited to global resources and those associated with the specified localization.

class func path(forResource: String?, ofType: String?, inDirectory: String)

Returns the full pathname for the resource file identified by the specified name and extension and residing in a given bundle directory.

class func paths(forResourcesOfType: String?, inDirectory: String)

Returns an array containing the pathnames for all bundle resources having the specified extension and residing in the bundle directory at the specified path.

Finding Image Resources

func urlForImageResource(String)

Returns the location of the specified image resource as an NSURL.

func pathForImageResource(String)

Returns the location of the specified image resource file.

func image(forResource: String)

Returns an NSImage instance associated with the specified name, which can be backed by multiple files representing different resolution versions of the image.

Finding Sound Resources

func path(forSoundResource: String)

Returns the location of the specified sound resource file.

Fetching Localized Strings

func localizedString(forKey: String, value: String?, table: String?)

Returns a localized version of the string designated by the specified key and residing in the specified table.

Fetching Context Help Resources

func contextHelp(forKey: String)

Returns the context-sensitive help for the specified key from the bundle's help file.

Getting the Standard Bundle Directories

var resourceURL: URL?

The file URL of the bundle’s subdirectory containing resource files.

var executableURL: URL?

The file URL of the receiver's executable file.

var privateFrameworksURL: URL?

The file URL of the bundle’s subdirectory containing private frameworks.

var sharedFrameworksURL: URL?

The file URL of the receiver's subdirectory containing shared frameworks.

var builtInPlugInsURL: URL?

The file URL of the receiver's subdirectory containing plug-ins.

func url(forAuxiliaryExecutable: String)

Returns the file URL of the executable with the specified name in the receiver’s bundle.

var sharedSupportURL: URL?

The file URL of the bundle’s subdirectory containing shared support files.

var appStoreReceiptURL: URL?

The file URL for the bundle’s App Store receipt.

var resourcePath: String?

The full pathname of the bundle’s subdirectory containing resources.

var executablePath: String?

The full pathname of the receiver's executable file.

var privateFrameworksPath: String?

The full pathname of the bundle’s subdirectory containing private frameworks.

var sharedFrameworksPath: String?

The full pathname of the bundle’s subdirectory containing shared frameworks.

var builtInPlugInsPath: String?

The full pathname of the receiver's subdirectory containing plug-ins.

func path(forAuxiliaryExecutable: String)

Returns the full pathname of the executable with the specified name in the receiver’s bundle.

var sharedSupportPath: String?

The full pathname of the bundle’s subdirectory containing shared support files.

Getting Bundle Information

var bundleURL: URL

The full URL of the receiver’s bundle directory.

var bundlePath: String

The full pathname of the receiver’s bundle directory.

var bundleIdentifier: String?

The receiver’s bundle identifier.

var infoDictionary: [String : Any]?

A dictionary, constructed from the bundle's Info.plist file, that contains information about the receiver.

func object(forInfoDictionaryKey: String)

Returns the value associated with the specified key in the receiver's information property list.

Getting Localization Information

var localizations: [String]

A list of all the localizations contained in the bundle.

var preferredLocalizations: [String]

An ordered list of preferred localizations contained in the bundle.

var developmentLocalization: String?

The localization for the development language.

var localizedInfoDictionary: [String : Any]?

A dictionary with the keys from the bundle’s localized property list.

class func preferredLocalizations(from: [String])

Returns one or more localizations from the specified list that a bundle object would use to locate resources for the current user.

class func preferredLocalizations(from: [String], forPreferences: [String]?)

Returns the localizations that a bundle object would prefer, given the specified bundle and user’s language preferences.

Managing Preservation Priority for On Demand Resources

func setPreservationPriority(Double, forTags: Set<String>)

A hint to the system of the relative order for purging tagged sets of resources in the bundle.

func preservationPriority(forTag: String)

Returns the current preservation priority for the specified tag.

Getting Classes from a Bundle

func classNamed(String)

Returns the Class object for the specified name.

var principalClass: AnyClass?

The bundle’s principal class.

Loading Code from a Bundle

var executableArchitectures: [NSNumber]?

An array of numbers indicating the architecture types supported by the bundle’s executable.

func preflight()

Returns a Boolean value indicating whether the bundle’s executable code could be loaded successfully.

func load()

Dynamically loads the bundle’s executable code into a running program, if the code has not already been loaded.

func loadAndReturnError()

Loads the bundle’s executable code and returns any errors.

func unload()

Unloads the code associated with the receiver.

var isLoaded: Bool

The load status of a bundle.

Constants

Mach-O Architecture

These constants describe the CPU types that a bundle’s executable code may support.

UIKit Nib Loading Options

The options that can be specified during nib loading.

NSLoadedClasses

This constant is provided in the userInfo dictionary of the didLoadNotification notification.

Notifications

class let didLoadNotification: NSNotification.Name

NSBundle posts didLoadNotification to notify observers which classes and categories have been dynamically loaded.

Relationships

Inherits From

Conforms To