How To Install

Authors: Jörg Jacobsen, Christoph Priebe

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 of Mac App Store) / 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. 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)

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

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

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

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

7. Tell your app where to find the iMedia framework: Your application binary and 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

1. Apply steps 1-7 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: 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)
4. 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 and Read/Write Access to the Downloads folder

While at it, you might like to allow your app to create security scoped bookmarks in case your app likes to save image URLs obtained from iMedia. To do so, open the entitlement file in a text editor and add these entitlements (one or both depending on your needs):

<key>com.apple.security.files.bookmarks.app-scope</key>
<true/>
<key>com.apple.security.files.bookmarks.document-scope</key>
<true/>

###XPCKit

1. Add XPCKit as a submodule to your app: git submodule add https://github.com/iMediaSandboxing/XPCKit.git Frameworks/XPCKit. Alternatively clone XPCKit (git clone https://github.com/iMediaSandboxing/XPCKit.git) and move the framework to your project folder.
2. Add XPCKit.xcodeproj project to your workspace or add it as a sub-project to your app
3. Open the XPCKit project and locate Poducts > XPCKit.framework
4. Drag & Drop XPCKit.framework to Build Phases > Target Dependencies
5. Drag & Drop XPCKit.framework to Build Phases > Link Binaries With Libraries
6. Drag & Drop XPCKit.framework to Build Phases > Copy Frameworks

Clone submodules

The iMedia Browser depends on other frameworks (also hosted in git repositories) that are hooked to its repository via the git "submodules" feature. These currently are

• XPCKit (as of iMedia release-3.0)

To clone these submodules to your local system and to checkout their right (iMedia compatible that is) version you must execute the following git commands:

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

Provide 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.