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 pithy 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

  • Make sure that the active target in Xcode is PhotoSection > iPhone (some version) Simulator. This should already be the case, but check anyway because adding Kiwi to the workspace would have caused more targets to become available.

11

3. @try-ing to use Kiwi

  • First, a note. There are a number of configuration issues involved when using Kiwi. For instructional purposes, this guide purposefully fixes these issue only as they are encountered to simulate the typical problems many people face when setting up libraries like Kiwi for iOS projects.
  • Now that we have Kiwi in our workspace, let's create a Kiwi spec (or test) file.
  • Create a new empty file called MathSpec.m. I recommend using the Other->Empty file template to avoid the noise present in the other file templates. Note that you do not need a .h file because the spec will be defined completely in the .m .
  • It is neater if MathSpec.m is created in the Tests group in the Project Navigator.
  • Importantly, make sure that during the file creation phase, MathSpec.m is added to the PhotoSection Tests target, and not the PhotoSection target. Every spec/test file you ever create should only ever be added to test target, or the compiled source for the spec will end up in your app!

12

In Progress

Add a custom footer

Kiwi 2.0

Clone this wiki locally