Up

# NSBundle class reference

### Authors

Adam Fedor (`fedor@boulder.colorado.edu`)
Mirko Viviani (`mirko.viviani@rccr.cremona.it`)
Nicola Pero (`nicola@brainstorm.co.uk`)

Copyright: (C) 1995, 1997, 1999, 2001, 2002 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the NSBundle class
2. Software documentation for the NSBundle(GNUstep) category

# Software documentation for the NSBundle class

## NSBundle : NSObject

> Declared in:
>   Foundation/NSBundle.h

Availability: OpenStep

NSBundle provides methods for locating and handling application (and tool) resources at runtime. Resources includes any time of file that the application might need, such as images, nib (gorm or gmodel) files, localization files, and any other type of file that an application might need to use to function. Resources also include executable code, which can be dynamically linked into the application at runtime. These files and executable code are commonly put together into a directory called a bundle.

NSBundle knows how these bundles are organized and can search for files inside a bundle. NSBundle also handles locating the executable code, linking this in and initializing any classes that are located in the code. NSBundle also handles Frameworks, which are basically a bundle that contains a library archive. The organization of a framework is a little difference, but in most respects there is no difference between a bundle and a framework.

There is one special bundle, called the mainBundle, which is basically the application itself. The mainBundle is always loaded (of course), but you can still perform other operations on the mainBundle, such as searching for files, just as with any other bundle.

Instance Variables
Method summary

- +bundleForLibrary:
- +bundleForLibrary:version:
- +pathForLibraryResource:ofType:inDirectory:
- +URLForResource:withExtension:subdirectory:inBundleWithURL:
- +allBundles
- +allFrameworks
- +bundleForClass:
- +bundleWithIdentifier:
- +bundleWithPath:
- +bundleWithURL:
- +mainBundle
- +pathForResource:ofType:inDirectory:
- +pathForResource:ofType:inDirectory:withVersion:
- +pathsForResourcesOfType:inDirectory:
- +preferredLocalizationsFromArray:
- +preferredLocalizationsFromArray:forPreferences:
- -URLForAuxiliaryExecutable:
- -URLForResource:withExtension:
- -URLForResource:withExtension:subdirectory:
- -URLForResource:withExtension:subdirectory:localization:
- -builtInPlugInsPath
- -builtInPlugInsURL
- -bundleIdentifier
- -bundlePath
- -bundleURL
- -bundleVersion
- -classNamed:
- -developmentLocalization
- -executableArchitectures
- -executablePath
- -executableURL
- -infoDictionary
- -initWithPath:
- -initWithURL:
- -isLoaded
- -load
- -loadAndReturnError:
- -localizations
- -localizedInfoDictionary
- -localizedStringForKey:value:table:
- -objectForInfoDictionaryKey:
- -pathForAuxiliaryExecutable:
- -pathForResource:ofType:
- -pathForResource:ofType:inDirectory:
- -pathForResource:ofType:inDirectory:forLocalization:
- -pathsForResourcesOfType:inDirectory:
- -pathsForResourcesOfType:inDirectory:forLocalization:
- -preferredLocalizations
- -preflightAndReturnError:
- -principalClass
- -privateFrameworksPath
- -privateFrameworksURL
- -resourcePath
- -resourceURL
- -setBundleVersion:
- -unload

### URLForResource: withExtension: subdirectory: inBundleWithURL:

+ (NSURL*) URLForResource: (NSString*)name withExtension: (NSString*)extension subdirectory: (NSString*)subpath inBundleWithURL: (NSURL*)bundleURL;
Availability: MacOS-X 10.6.0
Description forthcoming.

### allBundles

+ (NSArray*) allBundles;
Availability: OpenStep
Return an array enumerating all the bundles in the application. This does not include frameworks.
Returns an array of all the bundles which do not belong to frameworks.
This always contains the main bundle.

### allFrameworks

+ (NSArray*) allFrameworks;
Availability: OpenStep
Return an array enumerating all the frameworks in the application. This does not include normal bundles.
Returns an array containing all the known bundles representing frameworks.

### bundleForClass:

+ (NSBundle*) bundleForClass: (Class)aClass;
Availability: OpenStep

Return the bundle to which aClass belongs. If aClass was loaded from a bundle, return the bundle; if it belongs to a framework (either a framework linked into the application, or loaded dynamically), return the framework; if it belongs to a library, return the bundle for that library; in all other cases, return the main bundle.

Please note that GNUstep supports plain shared libraries, while the openstep standard, and other openstep-like systems, do not; the behaviour when aClass belongs to a plain shared library is to return a bundle for that library, but might be changed. :-)

Returns the bundle whose code contains the specified class.
NB: We will not find a class if the bundle has not been loaded yet!

### bundleWithIdentifier:

+ (NSBundle*) bundleWithIdentifier: (NSString*)identifier;
Availability: OpenStep
Returns the bundle for the specified identifier (see -bundleIdentifier) as long as the bundle has already been loaded. This never causes a bundle to be loaded.

### bundleWithPath:

+ (NSBundle*) bundleWithPath: (NSString*)path;
Availability: OpenStep
Return a bundle for the path at path. If path doesn't exist or is not readable, return `nil`. If you want the main bundle of an application or a tool, it's better if you use +mainBundle .

### bundleWithURL:

+ (NSBundle*) bundleWithURL: (NSURL*)url;
Availability: MacOS-X 10.6.0
Description forthcoming.

### mainBundle

+ (NSBundle*) mainBundle;
Availability: OpenStep

Return the bundle containing the resources for the executable. If the executable is an application, this is the main application bundle (the xxx.app directory); if the executable is a tool, this is a bundle 'naturally' associated with the tool: if the tool executable is xxx/Tools/ix86/linux-gnu/gnu-gnu-gnu/Control then the tool's main bundle directory is xxx/Tools/Resources/Control.

NB: traditionally tools didn't have a main bundle -- this is a recent GNUstep extension, but it's quite nice and it's here to stay.

The main bundle is where the application should put all of its resources, such as support files (images, html, rtf, txt,...), localization tables,.gorm (.nib) files, etc. gnustep-make (/ProjectCenter) allows you to easily specify the resource files to put in the main bundle when you create an application or a tool.

For an application, returns the main bundle of the application.
For a tool, returns the main bundle associated with the tool.
For an application, the structure is as follows -

The executable is Gomoku.app/ix86/linux-gnu/gnu-gnu-gnu/Gomoku and the main bundle directory is Gomoku.app/.

For a tool, the structure is as follows -

The executable is xxx/Tools/ix86/linux-gnu/gnu-gnu-gnu/Control and the main bundle directory is xxx/Tools/Resources/Control.

(when the tool has not yet been installed, it's similar - xxx/obj/ix86/linux-gnu/gnu-gnu-gnu/Control and the main bundle directory is xxx/Resources/Control).

(For a flattened structure, the structure is the same without the ix86/linux-gnu/gnu-gnu-gnu directories).

### pathForResource: ofType: inDirectory:

+ (NSString*) pathForResource: (NSString*)name ofType: (NSString*)extension inDirectory: (NSString*)bundlePath;
Availability: OpenStep
Returns an absolute path for a resource name with the extension in the specified bundlePath. See also -pathForResource:ofType:inDirectory: for more information on searching a bundle.

### pathForResource: ofType: inDirectory: withVersion:

+ (NSString*) pathForResource: (NSString*)name ofType: (NSString*)extension inDirectory: (NSString*)bundlePath withVersion: (int)version;
Availability: OpenStep
This method has been deprecated. Version numbers were never implemented so this method behaves exactly like +pathForResource:ofType:inDirectory: .

### pathsForResourcesOfType: inDirectory:

+ (NSArray*) pathsForResourcesOfType: (NSString*)extension inDirectory: (NSString*)bundlePath;
Availability: OpenStep

Returns an array of paths for all resources with the specified extension and residing in the bundlePath directory. bundlePath can be any type of directory structure, but typically it is used to search for resources in a application or framework. For example, one could search for tiff files in the MyApp.app application using [NSBundle pathsForResourcesOfType: @"tiff" inDirectory: @"MyApp.app"]. It will search in any Resources subdirectory inside bundlePath as well as the main directory for resource files. If extension is `nil` or empty, all resources are returned.

### preferredLocalizationsFromArray:

+ (NSArray*) preferredLocalizationsFromArray: (NSArray*)localizationsArray;
Availability: MacOS-X 10.0.0
Returns subarray of given array containing those localizations that are used to locate resources given environment and user preferences.

### preferredLocalizationsFromArray: forPreferences:

+ (NSArray*) preferredLocalizationsFromArray: (NSArray*)localizationsArray forPreferences: (NSArray*)preferencesArray;
Availability: MacOS-X 10.0.0
Returns subarray of given array containing those localizations that are used to locate resources given environment given user preferences (which are used instead of looking up the preferences of the current user).

### URLForAuxiliaryExecutable:

- (NSURL*) URLForAuxiliaryExecutable: (NSString*)executableName;
Availability: MacOS-X 10.6.0
Description forthcoming.

### URLForResource: withExtension:

- (NSURL*) URLForResource: (NSString*)name withExtension: (NSString*)extension;
Availability: MacOS-X 10.6.0
Description forthcoming.

### URLForResource: withExtension: subdirectory:

- (NSURL*) URLForResource: (NSString*)name withExtension: (NSString*)extension subdirectory: (NSString*)subpath;
Availability: MacOS-X 10.6.0
Description forthcoming.

### URLForResource: withExtension: subdirectory: localization:

- (NSURL*) URLForResource: (NSString*)name withExtension: (NSString*)extension subdirectory: (NSString*)subpath localization: (NSString*)localizationName;
Availability: MacOS-X 10.6.0
Description forthcoming.

### builtInPlugInsPath

- (NSString*) builtInPlugInsPath;
Availability: OpenStep
Returns the full path to the plug-in subdirectory of the bundle.

### builtInPlugInsURL

- (NSURL*) builtInPlugInsURL;
Availability: MacOS-X 10.6.0
Returns the full path to the plug-in subdirectory of the bundle.

### bundleIdentifier

- (NSString*) bundleIdentifier;
Availability: OpenStep
Returns the bundle identifier, as defined by the CFBundleIdentifier key in the infoDictionary

### bundlePath

- (NSString*) bundlePath;
Availability: OpenStep
Return the path to the bundle - an absolute path.

### bundleURL

- (NSURL*) bundleURL;
Availability: MacOS-X 10.6.0
Description forthcoming.

### bundleVersion

- (unsigned) bundleVersion;
Availability: OpenStep
Returns the bundle version.

### classNamed:

- (Class) classNamed: (NSString*)className;
Availability: OpenStep
Returns the class in the bundle with the given name. If no class of this name exists in the bundle, then Nil is returned.

### developmentLocalization

- (NSString*) developmentLocalization;
Availability: MacOS-X 10.2.0
Not implemented

### executableArchitectures

- (NSArray*) executableArchitectures;
Availability: MacOS-X 10.5.0
Not implemented

### executablePath

- (NSString*) executablePath;
Availability: MacOS-X 10.0.0
Returns the path to the executable code in the bundle

### executableURL

- (NSURL*) executableURL;
Availability: MacOS-X 10.6.0
Description forthcoming.

### infoDictionary

- (NSDictionary*) infoDictionary;
Availability: MacOS-X 10.0.0
Returns the info property list associated with the bundle.

### initWithPath:

- (id) initWithPath: (NSString*)path;
Availability: OpenStep
This is a designated initialiser for the class.
Init the bundle for reading resources from path.
The MacOS-X documentation says that the path must be a full path to a directory on disk. However, it (in MacOS-X) version 10.3 at least) actually accepts relative paths too.
The GNUstep behavior is similar in that it accepts a relative path, but GNUstep converts it to an absolute path by referring to the current working directory when the is initialised, so an absolute path is then used and a warning message is printed.
On MacOS-X using a bundle initialised with a relative path will cause a crash if the current working directory is changed between the point at which the bundle was initialised and that at which it is used.
If path is `nil` or can't be accessed, initWithPath: deallocates the receiver and returns `nil`.
If a bundle for that path already existed, it is returned in place of the receiver (and the receiver is deallocated).
If the -bundleIdentifier is not `nil`, and a bundle with the same identifier already exists, the existing bundle is returned in place of the receiver (and the receiver is deallocated).

### initWithURL:

- (id) initWithURL: (NSURL*)url;
Availability: MacOS-X 10.6.0
Description forthcoming.

### isLoaded

- (BOOL) isLoaded;
Availability: MacOS-X 10.2.0
Returns a boolean indicating whether code for the bundle has been loaded.
Returns `YES` if the receiver's code is loaded, otherwise, returns `NO`.

### load

- (BOOL) load;
Availability: MacOS-X 10.0.0
Loads any executable code contained in the bundle into the application. Load will be called implicitly if any information about the bundle classes is requested, such as -principalClass or -classNamed: .

### loadAndReturnError:

- (BOOL) loadAndReturnError: (NSError**)error;
Availability: MacOS-X 10.5.0
Not implemented

### localizations

- (NSArray*) localizations;
Availability: MacOS-X 10.0.0
Returns all the localizations in the bundle.

### localizedInfoDictionary

- (NSDictionary*) localizedInfoDictionary;
Availability: MacOS-X 10.2.0
Returns a localized info property list based on the preferred localization or the most appropriate localization if the preferred one cannot be found.

### localizedStringForKey: value: table:

- (NSString*) localizedStringForKey: (NSString*)key value: (NSString*)value table: (NSString*)tableName;
Availability: OpenStep

Returns the value for the key found in the strings file tableName, or Localizable.strings if tableName is `nil`.

If the user default `NSShowNonLocalizedStrings` is set, the value of the key will be returned as an uppercase string rather than any localized equivalent found. This can be useful during development to check where a given string in the UI is "coming from".

### objectForInfoDictionaryKey:

- (id) objectForInfoDictionaryKey: (NSString*)key;
Availability: MacOS-X 10.2.0
Not implemented

### pathForAuxiliaryExecutable:

- (NSString*) pathForAuxiliaryExecutable: (NSString*)executableName;
Availability: MacOS-X 10.0.0
Description forthcoming.

### pathForResource: ofType:

- (NSString*) pathForResource: (NSString*)name ofType: (NSString*)extension;
Availability: OpenStep
Returns an absolute path for a resource name with the extension in the receivers bundle path. See -pathForResource:ofType:inDirectory: .

### pathForResource: ofType: inDirectory:

- (NSString*) pathForResource: (NSString*)name ofType: (NSString*)extension inDirectory: (NSString*)subPath;
Availability: OpenStep

Returns an absolute path for a resource name with the extension in the specified bundlePath. Directories in the bundle are searched in the following order:

         root path/Resources/subPath
         root path/Resources/subPath/"language.lproj"
         root path/subPath
         root path/subPath/"language.lproj"

where language.lproj can be any localized language directory inside the bundle.

If extension is `nil` or empty, then the first file exactly matching name (ie with no extension) is returned.

### pathForResource: ofType: inDirectory: forLocalization:

- (NSString*) pathForResource: (NSString*)name ofType: (NSString*)extension inDirectory: (NSString*)subPath forLocalization: (NSString*)localizationName;
Availability: MacOS-X 10.0.0
This is like -pathForResource:ofType:inDirectory: but returns only resources matching localizationName (preferentially), or non-localized resources.

### pathsForResourcesOfType: inDirectory:

- (NSArray*) pathsForResourcesOfType: (NSString*)extension inDirectory: (NSString*)subPath;
Availability: OpenStep

Returns an array of paths for all resources with the specified extension and residing in the bundlePath directory. If extension is `nil` or empty, all bundle resources are returned.

### pathsForResourcesOfType: inDirectory: forLocalization:

- (NSArray*) pathsForResourcesOfType: (NSString*)extension inDirectory: (NSString*)subPath forLocalization: (NSString*)localizationName;
Availability: MacOS-X 10.0.0
This method returns the same information as -pathsForResourcesOfType:inDirectory: except that only non-localized resources and resources that match the localization localizationName are returned.
The GNUstep implementation places localised resources in the array before any non-localised resources.

### preferredLocalizations

- (NSArray*) preferredLocalizations;
Availability: MacOS-X 10.0.0
Returns the list of localizations that the bundle uses to search for information. This is based on the user's preferences.

### preflightAndReturnError:

- (BOOL) preflightAndReturnError: (NSError**)error;
Availability: MacOS-X 10.5.0
Not implemented

### principalClass

- (Class) principalClass;
Availability: OpenStep
Returns the principal class of the bundle. This is the class specified by the NSPrincipalClass key in the Info-gnustep property list contained in the bundle. If this key or the specified class is not found, the class returned is arbitrary, although it is typically the first class compiled into the archive.

### privateFrameworksPath

- (NSString*) privateFrameworksPath;
Availability: OpenStep
Returns the full path to the private frameworks subdirectory of the bundle.

### privateFrameworksURL

- (NSURL*) privateFrameworksURL;
Availability: MacOS-X 10.6.0
Returns the full path to the private frameworks subdirectory of the bundle.

### resourcePath

- (NSString*) resourcePath;
Availability: OpenStep
Returns the absolute path to the resources directory of the bundle.

### resourceURL

- (NSURL*) resourceURL;
Availability: MacOS-X 10.6.0
Returns the absolute path to the resources directory of the bundle.

### setBundleVersion:

- (void) setBundleVersion: (unsigned)version;
Availability: OpenStep
Set the bundle version

### unload

- (BOOL) unload;
Availability: MacOS-X 10.2.0
* Not implemented

## Instance Variables for NSBundle Class

### _bundleClasses

@public NSMutableArray* _bundleClasses;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _bundleType

@public unsigned int _bundleType;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _codeLoaded

@public BOOL _codeLoaded;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _frameworkVersion

@public NSString* _frameworkVersion;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _infoDict

@public NSDictionary* _infoDict;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _localizations

@public NSMutableDictionary* _localizations;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _path

@public NSString* _path;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _principalClass

@public Class _principalClass;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _version

@public unsigned int _version;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

# Software documentation for the NSBundle(GNUstep) category

## NSBundle(GNUstep)

> Declared in:
>   Foundation/NSBundle.h

Availability: Base
Likely to be changed/moved/removed at 1.17.0
Augments NSBundle , including methods for handling libraries in the GNUstep fashion, for rapid localization, and other purposes.
Method summary

- +bundleForLibrary:
- +bundleForLibrary:version:
- +pathForLibraryResource:ofType:inDirectory:

### bundleForLibrary:

+ (NSBundle*) bundleForLibrary: (NSString*)libraryName;
Availability: Base
Likely to be changed/moved/removed at 1.17.0
This method is a equivalent to bundleForLibrary:version: with a `nil` version.

### bundleForLibrary: version:

+ (NSBundle*) bundleForLibrary: (NSString*)libraryName version: (NSString*)interfaceVersion;
Availability: Base
Likely to be changed/moved/removed at 1.17.0
This method is an experimental GNUstep extension, and might change.

Return a bundle to access the resources for the (static or shared) library libraryName , with interface version interfaceVersion.

Resources for shared libraries are stored into GNUSTEP_LIBRARY/Libraries/libraryName/Versions/interfaceVersion/Resources/; this method will search for the first such existing directory and return it.

libraryName should be the name of a library without the lib prefix or any extensions; interfaceVersion is the interface version of the library (eg, it's 1.13 in libgnustep-base.so.1.13; see library.make on how to control it).

This method exists to provide resource bundles for libraries and has no particular relationship to the library code itsself. The named library could be a dynamic library linked in to the running program, a static library (whose code may not even exist on the host machine except where it is linked in to the program), or even a library which is not linked into the program at all (eg. where you want to share resources provided for a library you do not actually use).

The bundle for the library gnustep-base is a special case... for this bundle the -principalClass method returns NSObject and the -executablePath method returns the path to the gnustep-base dynamic library (if it can be found). As a general rule, library bundles are not guaranteed to return values for these methods as the library may not exist on disk.

### pathForLibraryResource: ofType: inDirectory:

+ (NSString*) pathForLibraryResource: (NSString*)name ofType: (NSString*)extension inDirectory: (NSString*)bundlePath;
Availability: Base
Likely to be changed/moved/removed at 1.17.0
Find a resource in the "Library" directory.

Up