Permalink
Browse files

Added README for LibraryWithRsrc

  • Loading branch information...
1 parent 70ddbd7 commit c7fc92179bae79ca2c969b75638d631818e4cef2 @AliSoftware committed Jan 16, 2013
Showing with 79 additions and 1 deletion.
  1. +78 −0 LibraryWithRsrc/README.md
  2. +1 −1 README.md
View
@@ -0,0 +1,78 @@
+## LibraryWithRsrc
+
+This is an example of how to create a Xcode projet that generate **both** a static library **and** a _resource bundle_.
+
+The aim of this project is to show how you can have a library that provide both functional code but also **resources like
+XIB files, PNG files, xcdatamodels, and even Localized strings**, without the need for you to copy
+each and every single resource in your application project.
+
+There are a lot of advantages in this practice:
+
+* Your library can provide `UIViewControllers` that are based on XIB files if necessary, and the XIB files will be provided by the library
+ and not need to be copied in the application for this to work
+* If your XIB files (used and provided by the library and its resource bundle) use themselves some images in an `UIImageView`,
+ the image will be loaded from the same bundle than the XIB, namely the resource bundle provided by the library too, and not the application
+* If your library needs to provide some localized strings, there is no need to merge your own `Localizable.strings` of your app
+ with the strings needed for the library: the library will have its own `Localizable.strings` and will be able to pick localized strings
+ from it instead of the one from the application itself.
+
+Once you have implemented a simple method in your library main class that returns an `NSBundle` object that will represent the
+resource bundle generated by the library (see demo project), you can use all the standard methods of `NSBundle` like
+`pathForResource:ofType:` and `localizedStringForKey:value:table:` to retrieve those resources.
+
+For images, the `+[UIImage imageNamed:inBundle:]` method is unfortunately a private method, but the demo project provides a workaround
+(see the `UIImage+Bundle.h` category in the demo project).
+
+## Example usages
+
+You can imagine using this pattern for example to create a library that will provide some standard widgets / custom views / reusable control
+(or even View Controllers) that you reuse a lot in your various applications.
+
+Even if those views will be embedded in a static library, you can design their interface using XIB files,
+use PNG images when needed to design those custom views, provide localized strings so your reusable control
+support multiple languages natively, and so on…
+As long as you use the methods of `NSBundle` in your library code to make sure to retrieve the XIB, PNG, Localized strings
+and other resources from the resource bundle (and not the resources of your future host application), you will have a standalone reusable control!
+
+All you will need to do to use them in your applications then is to link the application with the static library
+of course, and add the resource bundle that your project generated with the static library (thanks to a second, dedicated target)
+to the resources of your app.
+
+## How to generate a valid resource bundle
+
+Since Xcode 4 does not provide a template to generate a Resource Bundle for iOS, you will use the template for OSX bundles
+and then need to adjust the Build Settings to adapt it:
+
+* In your project that generates your static library, in addition to the "Static Library" target, add a New Target using the
+"Bundle" template of the OSX "Framework & Library" template section
+* Go to the Build Settings of this newly generated template, and delete the following key
+ (i.e. select their line and hit the delete key, to remove the custom value propose and so that they use the default values instead):
+ * `Base SDK`
+ * `Architectures`
+ * `OSX Deployment Target`
+ * `Installation Directory`
+ * `Prefix Header`
+ * `COMBINE_HIDPI_IMAGES`
+* Set the `Skip Install` Build Settings to `YES` if not already
+* Remove the `".pch"` file (we are building a resource bundle, we won't have any code in this target)
+* In the `Info.plist` file, remove useless keys like `"pluginXXX"` and `"Executable File"`
+
+Finally, you may reorganize the remaining files if needed (for example I often remove the `InfoPlist.strings` file and
+move the `Info.plist` file at some other place and remove the `Supporting Files` folder, just to keep stuff as clean as possible)
+
+Once this Resource Bundle target is configured:
+
+* Add it as an explicit dependency to your static library, so that every project (typically your host application projet) that is linked
+and dependent to your static library will ensure first that the bundle has been compiled first.
+* Add your resource files (PNG, XIB, Localized.string, PLIST data files, xcdatamodel, …) to your bundle target so that
+ those resources will be embedded in the bundle
+* Build the bundle target once, for "iOS Device" (not for the simulator). The file should then change from red (inexistant)
+ to black (file exists) in the "Products" group in your Project Navigator on the left.
+* Select the generated bundle in the "Products" group in your Project Navigator, and right-click to choose "Show in Finder"
+* Once the generated bundle has been highlighted in the Finder, drag & drop it on Xcode, on the Project Navigator,
+ under your application's Xcode project (for example right below the ".a" static library you should have around here too).
+ _This way the resource bundle will be copied and embedded inside the generated application during the compilation._
+
+> Note that since modifying a resource does not seem to modify the "modification date" of the bundle that contains the resource,
+Xcode may sometimes not detect that it needs to rebuild your resource bundle when a resource has been added to it or modified.
+In that case, the easiest solution is to clean and rebuild your resource bundle to be sure it contains the latest resources.
View
@@ -4,7 +4,7 @@ This repository aims to share some useful resources for Xcode and other Develope
This folder contains some File Templates so you can have a nice and homogeneous organization of your code in all your files.
-## [LibraryWithRsrc](Xcode-Utils/tree/master/LibraryWithRsrc) : Static Library **with Resource Bundle** to provide XIB, PNG & others
+## [LibraryWithRsrc](Xcode-Utils/tree/master/LibraryWithRsrc) : Static Library **with Resource Bundle**
This is an example of how to create a Xcode projet that generate **both** a static library **and** a _resource bundle_.

0 comments on commit c7fc921

Please sign in to comment.