Getting started

Getting Started

Installing Kit

You'll need the latest haskell platform release for OS X. Kit installs through haskell's package manager:

$ brew install haskell-platform # If you've got brew, otherwise: http://hackage.haskell.org/platform/mac.html
# Add ~/Library/Haskell/bin to your PATH
$ cabal update
$ cabal install kit
$ kit --version # this is how you know it's working. If it's not yet working, maybe ~/Library/Haskell/bin isn't on your path

Kit combines the Objective-C projects you depend on into one super dependency, called KitDeps. The super dependency builds everything into one static library that you use in your project.

Making a Kit

Projects that form dependencies are called kits. Imagine you had some classes for doing logging. Call it logface. Whatever. You lay out your project directory like this:

src/ -- all your source goes here. Headers and implementation. 
        This directory is placed in the HEADER_SEARCH_PATH for 
        projects that consume this kit.
test/ -- they'll be included when the kit is bundled, but aren't used by kit at the moment
Config.xcconfig -- any special project settings that your library needs
KitSpec -- A yaml file telling kit what the project is. We'll get to this soon.

Now that we've obeyed kit's demands for project layout, we can populate the KitSpec file with the name, version, and dependencies of your project:

name: logface
version: 0.1
dependencies: []

It's yaml. At this point, I need to make quick point about versions. Kit is dumb. It does no version conflict checking, or resolution of suitable versions that satisfy all dependencies. If you depend on 2 different versions of a project, directly or indirectly, things will blow up.

Sharing a Kit

'logface' is looking pretty good now. So lets make it usable by our other projects. When kit looks for dependencies, it looks in your local cache: ~/.kit/cache/local. Kit knows how to stick stuff in it, and pull stuff out of it:

$ cd logface
$ kit publish-local
# This is where it was published to:
$ ls ~/.kit/cache/local/logface/0.1

Using a kit

Now we kick off with our main business: writing our app, Angry Fruit Ninja III, and it needs a logging library. First, we make our app a kit by giving it a KitSpec. We're not going to publish this one though. We're using the KitSpec to declare a dependency on logface.

$ cd angry-fruit-ninja-iii
$ cat KitSpec 
name: angry-fruit-ninja-iii
version: 0.9
dependencies:
    - logface: 0.1 # Note the dash in front of this key/value. That's telling YAML that this is an entry in the dependencies list.

Now the money shot:

$ devkit update
 -> Using local package: logface-0.1
 -> Generating Xcode project...

    	Kit complete. You may need to restart Xcode for it to pick up any changes.

$ # Note existence of 'Kits' directory.

Kit has generated a project file that references content from your dependencies. The project is sitting in Kits/KitDeps.xcodeproj. The kits your project depended on have been extracted to .kit/packages and referenced from there.

To use the kits, modify Angry Fruit Ninja's Xcode project like so:

1. Add Kits/KitDeps.xcodeproj and Kits/Kit.xcconfig as items in your project. Group them up in a group named 'Kits' if you like.
2. All build configurations need to be based on Kits/Kit.xcconfig. If you use other xcconfig files, make sure they #include "Kits/Kit.xcconfig" at some point.
3. The app target should depend on KitDeps.xcodeproj. This means that Xcode will compile KitDeps before it compiles your project.
4. The app should link against libKitDeps.a, from KitDeps.xcodeproj.

Phew. And that's it.

Next Steps and Random Tips

Kit is missing a few key features so there are a few things you might like to know about how I (and my fellow devs at mogeneration) use it.

1. We have a lot of company IP built up in kits, so we can't publish our kit repository publicly. We keep all our kits in a private git repository that everyone clones into ~/.kit. Works a charm.
2. When we use external code, we create a fork on github. Then we massage the project into the structure kit likes and pop in a KitSpec. Then it's a matter of running publish-local, committing and pushing our private kit repo in ~/.kit (git managed, if you recall), then letting everyone know to update their copies.
3. kit verify is pretty cool. It tries to use the current kit as a dependency in an empty shell project. This will tell you if all your dependencies can be compiled together.