Skip to content

Guide: Up and Running with Kiwi

Jump to bottom Edit New page
allending edited this page Nov 13, 2011 · 42 revisions

This guide is meant to be a gentle introduction to setting up Kiwi and static libraries in general for use in your own projects. If you know what you are doing, this guide could be compressed to about 6 lines, but we will go into excruciating detail and fix common build problems as they arise to serve as a learning instrument.

We will start from scratch by setting up an iPhone project that is built with ARC, includes a test target, and is linked with a Kiwi static library.

This guide assumes and uses screenshots of Xcode 4.2 for illustrative purposes. The name of the sample project in the guide below will be PhotoSection, but it should be trivial to adapt for your own use.

1. Creating and Examining a New Project.

  • Create a new master detail iPhone project in Xcode 4.2, and call it PhotoSection. Make sure that the Use Automatic Reference Counting and Include Unit Tests options are checked during the project creation phase.

1

  • Click on the PhotoSection project in the Project Navigator on the left side of Xcode. We can see that Xcode has created an app target called PhotoSection and a test target called PhotoSection Tests.

2

  • Xcode also added starter test files called PhotoSectionTests.h and PhotoSectionTests.m. As you can see, I also did some tidying up of the project groups in the project navigator.

3

  • Let's examine the test target Xcode created for us. Click on the PhotoSection Tests target and then on Build Settings.
  • Find the Bundle Loader setting, and we can see that it is filled in.
  • Find the Test Host setting, and we can see that it is also filled in.
  • These two settings means that the test target that Xcode has created is an Application Unit Test Target.
  • For our purposes, this is fine.
  • You can find more details about what this means in comparison to a Logic Unit Test Target at the official Apple documentation here.

4

  • Click the PhotoSection app target and look through its build settings. The target is built with ARC (Automatic Reference Counting) enabled. Kiwi is not written to use ARC internally, but your own projects can be ARC enabled and link to a Kiwi static library without problems.

5

  • Run the Test action through the Product menu item, or by using Cmd-U. It works fine although we get alerted to a failing test in PhotoSectionTests.m.
  • This shows that the test target is working fine, so lets make a quick fix as in the image below to get the test passing. Once you have made the change below run the Test action again to verify the issue has been fixed.
  • We now have an iPhone project with a working test target. Time to move on to Kiwi.

6

2. Adding Kiwi to the Project

  • The best way to use Kiwi in your project is to set up an Xcode workspace that contains both your app project and the Kiwi project, which is what we will guide you through.
  • Checkout Kiwi from GitHub somewhere onto your machine.
  • Drag the Kiwi.xcodeproj file from OS X Finder directly into Xcode's Project Navigator.

7

  • Xcode will prompt you about creating a workspace. Accept, and create the workspace file somewhere that makes sense. For the example in this guide, we have saved the workspace file in the same directory as the project file.

8

  • Once the workspace has been created, you should also also see Kiwi in the project navigator.

9

  • Click on the Kiwi project in the Project Navigator. Then examine the Kiwi target (you can ignore the KiwiTests and KiwiExamples targets). You will be able to see that the Kiwi target builds a static library with ARC disabled.

10

In Progress

Add a custom footer

Kiwi 2.0

Clone this wiki locally