How To Install

Authors: Jörg Jacobsen, Christoph Priebe NOTE: This guide is work in progress NOTE: This guide assumes that your app is wrapped into an Xcode workspace. If it isn't you may want to consider doing it now (more on workspaces).

Choose your Scenario

iMedia 3 can adapt to your app's deployment needs along the following dimensions (choose any combination):

1. Sandboxed (in terms OS X) / non-sandboxed
2. With / without utilizing XPC services

Note regarding XPC services: When configured XPC services serve media fetching in respect to library types supported by iMedia (e.g. iPhoto or Lightroom libraries)

Let's start with the easiest configuration:

Scenario 1: Non-sandboxed and without utilizing XPC services

This is straight forward.

1. Add iMedia as a submodule to your app:

    $ git submodule add https://github.com/iMediaSandboxing/iMedia.git Frameworks/iMedia
   

   Or, if you don't use git as your app's versioning tool simply clone iMedia:

    $ git clone https://github.com/iMediaSandboxing/iMedia.git
   

   and move the framework to your project folder.

2. iMedia 3 depends on other frameworks (also hosted in git repositories) that are hooked to its repository via the git "submodules" feature. These frameworks currently are (as of iMedia 3.0)

   • ObjectiveFlickr
   • XPCKit

   To clone these submodules to your local system in their correct (iMedia compatible) version you must execute the following git commands from the root directory of your local iMedia git repo:

    $ git submodule init
    <some response from git>
    $ git submodule update
    <some response from git>
   

3. Add the iMedia.xcodeproj project file to your workspace or add it as a sub-project to your app (by dragging it into the navigator pane of Xcode)

4. Open the iMedia project in your app's workspace and locate Poducts > iMedia.framework

5. (This step only if you added iMedia as sub-project) Drag & Drop iMedia.framework to Build Phases > Target Dependencies

6. Drag & Drop iMedia.framework to Build Phases > Link Binaries With Libraries

7. Drag & Drop iMedia.framework to Build Phases > Copy Frameworks

8. Repeat steps 3,4,5 and 7 to the ObjectiveFlickr framework located in the root directory of the iMedia repository

9. You do not have to repeat steps 3,4,5 and 7 for the XPCKit framework since it is not utilized in this scenario

10. Tell your app where to find the iMedia framework: Your application binary and (principally) all XPC services associated with the iMedia framework will link with the iMedia framework located in the application's bundle. Since the (relative) path from the location of these binaries to the location of the app-embedded iMedia framework is (naturally) different, iMedia uses the @rpath variable to tell the loader where to find it (see also Linking and Install Names by Mike Ash). To set the @rpath variable you must set the Runpath Search Paths build setting to @loader_path/../Frameworks/Library/Frameworks for the target that builds your app's main binary.

Scenario 2: Sandboxed and without utilizing XPC services

If you are not yet familiar with app sandboxing on OS X you will like to first read Apple's App Sandboxing Design Guide.

1. Apply steps 1-10 as described in scenario 1
2. Select your application target and under Summary > Entitlements switch on Use Entitlements File and Enable App Sandboxing
3. Add the following entitlements to your app's entitlement file:
   1. com.apple.security.files.user-selected.read-write YES will enable the user to grant entitlements to directories where necessary when prompted (e.g. library sits on external volume)
   2. com.apple.security.files.bookmarks.app-scope YES will ensure that entitlements granted by the user will persist across sessions or even reboot of the system. This one is also mandatory if your app likes to save image URLs obtained from iMedia.
   3. com.apple.security.temporary-exception.shared-preference.read-only com.apple.iApps will enable iMedia to locate Aperture and iPhoto libraries (note that this entitlement must be set up as a one-element array)
   4. com.apple.security.temporary-exception.shared-preference.read-only com.adobe.Lightroom, com.adobe.Lightroom2,... will enable iMedia to locate Lightroom libraries of their respective version (note that you have to append those entitlements to the entitlement of step 3.2 if you applied step 3.2. Add one entry for each major Lightroom version you want to qualify)
   5. Add access to the resources your app needs. E.g. to use images, you like to at least have Read Access to the user's Pictures folder (you may set this on the summary page of your application target)

Scenario 3: Sandboxed and utilizing XPC services

Regardless of whether or not your app should run sandboxed the rule of whether or not your app utilizes iMedia XPC services says:

If you deploy an iMedia XPC service to your app's bundle it will be utilized. If you don't, GCD will be utilized instead.

Thus, to implement scenario 3 apply the following steps:

1. Apply steps 1-3 as described in scenario 2 but omit steps 3.2 - 3.4 (they won't harm execution of your app but Apple might not like superfluous entitlements on Mac App Store review). These entitlements are already granted to iMedia's XPC services where needed.
2. Apply steps 3,4,5 and 7 of scenario 1 to the XPCKit framework located in the root directory of the iMedia repository
3. Add build targets for all XPC services to your app's project (current XPC services are...)
4. @rpath all XPC services...

Scenario 4: Non-sandboxed and utilizing XPC Services

...

Provide a code signing certificate

The Test App provided with the repository is signed with the "3rd Party Application Developer" certificate. Make sure you either have repuested that certificate through your Mac Developer Program membership and installed it on your system or you changed the corresponding build setting to use one of your own certificates.