Creating a Kit

Overview

Walkthrough of creating a kit.

See also https://github.com/nkpart/kit/wiki/Getting-started

Initialise

By default, kit assumes the following structure for a project:

your-project/
    src/  -- source-directory
    lib/  -- lib-directory
    test/  -- test-directory
    KitSpec
    Config.xcconfig -- xcconfig
    Prefix.pch -- prefix-header

To create a kit, follow these steps:

1. If an external repo, fork it first. This lets you commit the changes & also allows easy merging of upstream changes.

2. Firstly, start with a known released tag, or branch, that way it's easier to find the upstream version if it's needed. Create a branch or whatever to base your work on. If there is no released version, consider using the commit SHA as the version (or a suffix to the version).

3. Create a KitSpec file in the root of the project, containing the name & version of the code.

    name: iso-8601-date-formatter
    version: 0.7.0
   

   If you end up modifying the source, consider appending a different suffix to the version string, for example if you modified version 0.7.0, make it 0.7.0-yourname, just to avoid confusion with upstream versions. Mark your tag names similarly.

4. Add project dependencies, these are other kits using the dependencies tag:

    name: iso-8601-date-formatter
    version: 0.7.0
    dependencies:
      - fmdb: 2.1
   

At this point, you should have enough to get a basic kit up & running, if it follows the default structure above, if not, read on.

Source

If you have the source code, follow these steps below. Note that sometimes it may be easier to build the library from its own build scripts, see below for this.

1. By default, kit will look for source in an src directory, if source lives in a different spot, set the source-directory:

    name: iso-8601-date-formatter
    version: 0.7.0
    source-directory: src
   

   If the source lives in an odd spot, say in the root, or, maybe in several locations, you can create a src directory, and create symlinks inside it to the other relevant source (or just symlink an src to the project's source tree).

2. Set the arc requirements of the project using the with-arc flag:

    name: iso-8601-date-formatter
    version: 0.7.0
    source-directory: src
    with-arc: false
   

3. Verify the kit you've created is correct:

    $ kit verify
   

   This will run some pre-flight checks and then create & build an Xcode project.

4. Tag the repo (keep the the naming convention of existing repo, using a suffix if you changed stuff):

    $ git add --all && git commit -m 'Kitted up project.' && git push
    $ git tag -a -m 'v0.7.0' 0.7.0 && git push --tags
   

5. Publish the kit:

    $ kit publish-local
    $ cd ~/.kits
    $ git add --all && git commit -m 'updated kits' && git push
   

6. Tell people.

Source, Using a Build Script

Some projects have complicated dependencies (e.g. git submodules) or require custom build scripts to run. It may be easier in this case to build the library & make a static library kit instead of using the source. ReactiveCocoa) is like this for example. In this case, it's good to create a kitbuild script (the name can be anything) that builds the library, and then make a static library kit instead:

	#!/bin/bash
	# Script to build a library for use in a kit, modelled off script/cibuild

	cd "$(dirname "$0")/ReactiveCocoaFramework"
	BUILD_DIR="$PWD/build"
	LIB_DIR="$PWD/../lib"
	SRC_DIR="$PWD/../src"

	# clean up
	rm -rf $LIB_DIR/libReactiveCocoa-iOS.a
	rm -rf $SRC_DIR/*.h
	xcodebuild -alltargets clean OBJROOT=$BUILD_DIR SYMROOT=$BUILD_DIR

	# build library
	xcodebuild -configuration release -target ReactiveCocoa-iOS build OBJROOT=$BUILD_DIR SYMROOT=$BUILD_DIR || exit $?
	cp $BUILD_DIR/Release-iphoneos/libReactiveCocoa-iOS.a $LIB_DIR/libReactiveCocoa-iOS.a
	cp -r $BUILD_DIR/Release-iphoneos/include/ReactiveCocoa/* $SRC_DIR/

	echo "Kit build complete, 'kit publish-local' to re-publish the kit."

Static Library

If a static library, follow these steps:

1. Get the static library & it's header files.

2. Create the KitSpec as normal, you will only need some of the settings (e.g. static libs don't need ARC):

    name: ReactiveCocoa 
    version: 2.1.6
   

3. Create a lib dir, put the static library in that.

    $ ls -l lib/
    total 10072
    -rw-rw----  1 tom  admin   4.9M  8 Nov 10:18 libReactiveCocoa-iOS.a
   

4. Create a src dir, put the header files in there.

    $ ll src/
    total 688
    -rw-rw----  1 tom  admin   2.3K  8 Nov 10:18 EXTKeyPathCoding.h
    -rw-rw----  1 tom  admin   3.5K  8 Nov 10:18 EXTScope.h
    ...
   

5. Run the same kit verification steps as above.

Note. There is a bug in Xcode whereby a static library project (e.g. KitDeps) containing only one static library project (i.e. with no source) will not be built as a dependent project when you build the main project, i.e. your project will not build KitDeps.

Special Options

If the project requires custom build settings (e.g. OTHER_LDFLAGS), create a Config.xcconfig file in the root of the project, and add in the properties required:

OTHER_LDFLAGS = $(OTHER_LDFLAGS) -ObjC
HEADER_SEARCH_PATHS = "$(BUILD_ROOT)/../IntermediateBuildFilesPath/UninstalledProducts/include" $(inherited)

Note that kit will chain these correctly, so if say a library requires -ObjC to be set, kit will propagate that up to the project that depends on this project.

You can also use kitdeps-xcode-flags:

	kitdeps-xcode-flags: "#include \"../MyProjectAndKits.xcconfig\"\n#include \"../KitOnly.xcconfig\"\n"