Kiwi 2.0 - Installing/configuring Kiwi

[allending]

Lets tackle streamlined installation as the first task in 2.0 as I think that is the biggest barrier to entry for new uses.

I'd like to get feedback on how people are installing/using Kiwi in their projects in terms of configuration.

The current documentation (https://github.com/allending/Kiwi/wiki/Guide:-Up-and-Running-with-Kiwi) requires adding the Kiwi project directly to the main project and creating a test target.

What sucks:

• The current install process has way too many steps. This leads to many ways to configure Kiwi usage wrongly and causes user frustration.
• There are various other ways advanced users can configure Kiwi for use which is non-supported officially and may break at any time
• Git submodules are confusing and scare developers
• Current versioning is an absolute PITA

My current thoughts:

• This needs to be as drag and drop as possible
• I really really really want there to be one correct way to use the library, targeting production environments. Fragmentation leads to confusion.
• Highly discourage checking out the Kiwi repository unless you are developing Kiwi.
• Simplify usage of library: provide official versions on the static versioned libKiwi.a library, and headers
• Setup process involves referencing the static lib, configuring target with needed flags to prevent elision of symbols, and adding headers to search path.
• Should we consider making a framework for this?
• A script to automate setting up targets correctly?
• In general, and especially with the intended better planned roadmap, we will keep the main repository for development purposes and users should generally be using a stable version of Kiwi in production.
• Officially support CocoaPods installation (better docs, description, etc)?

What are your thoughts? What can we do to make this elegant?

[dimsumthinking]

I think your analysis is spot on. If I were able to see the future it looks as if Apple is working to address this with their module proposals but that doesn't help us at this point.

I like the idea of having a static versioned libKiwi.a library and headers.

You may want to narrow your focus by just saying Kiwi 2.0 is for ARC projects.

There seem to be enough requests for Kiwi for OS X projects that we need to think about installations for both platforms.

I don't know if you need to worry about a framework or target - just clear instructions (i.e. Go to Build Phases and do this...) should be fine. That said - maybe a simple prebaked target might be nice ...

[eraserhd]

My thoughts, for what they're worth:

1. CocoaPods - It's a whole lot closer to "just working" recently. My last quick project was up and running in 20 minutes.
2. A scripted boot, like rvm (curl https://example.com/install.sh |sh), because:

• Install has been painful for me in the past. This is easy.
• How to install changed at one point, and I wasn't aware of it. I wouldn't have to think about that.
• I'm guessing there are people who aren't yet interested in CocoaPods.

[supermarin]

@eraserhd totally agree.

One more - what about providing a plug and play .framework download, that doesn't have to be compiled by the end user?

[allending]

https://github.com/kstenerud/iOS-Universal-Framework actually seems like it would really help with this - there would be official versioned framework drops of Kiwi. At that point, it's simply a matter of using the framework with the correctly configured target - no header headaches, clear versioning, etc.

I like CocoaPods a lot, but my main hesitation of making it the 'only' supported way is that there are developers who are hesitant about installing another software manager like tool on their machines. It also adds complexity in the sense that there will be one more prerequisite for using Kiwi. But definitely I'd keep CocoaPods support around.

Also, @shepting has a guide on OS X usage of Kiwi here, I think it would be great to integrate the documentation - https://github.com/shepting/kiwi-mac-demo. Also, a sample project really really makes sense. Not only in terms of showing how to configure Kiwi, but also as a gold standard for how tests should be written.

[shepting]

My vote for setup is obviously for CocoaPods but there's certainly no downside to having other directions as well.

I've added my Mac directions to this project as https://github.com/allending/Kiwi/wiki/Up-and-Running-with-Kiwi-for-Mac. I left the sample app where it is for the time being.

[allending]

Hey everyone, happy new year.. kinda.

I've been playing around with the framework approach and it is really appealing to me. It reduces the setup to these steps:

1. Download a framework package of Kiwi e.g. Kiwi.framework
2. Create a test target and add the framework to "link binary with libraries" in "build phases"
3. Add the -all_load linker flag
4. Start writing specs

2, 3, and 4 are pretty unavoidable (unless you use a script) in any case.

1 is awesome cause it pushes the versioning, packaging, and annoyance of how to add Kiwi to a project to the maintainers (us). It also more closely emulates how SenTestingKit is deployed by default when you use test targets.

• Maintainers can just work the same way as before, using repo directly if wanted.
• Users who don't care about developing Kiwi just use the framework.

Attaching an example of a built framework that works like described above.
https://www.dropbox.com/s/20yn6481ws1mujg/Kiwi.framework.zip

[jonah-williams]

I have a few arguments which make me favor CocoaPods.

1. While downloaded frameworks can contain version information and references to their origin it is less obvious than the convention of a podfile. As a developer joining a project I want it to be easy to identify which release of Kiwi the project uses, if it is up to date, and where it was obtained from (i.e. from allending or someone else's fork).
2. Kiwi is not and will not be the only third party library my application uses. Considering Kiwi in isolation the framework install process doesn't seem hard but I have never seen an app with only one such dependency. Managing multiple dependencies means I will want to use pods for them. Having Kiwi be an outlier from my default process for installing all other dependencies discourages me from using it or leaves me dependent on an unofficial (and possibly out of date) podfile to install it.
3. I want to be able to write tools which depend on Kiwi. When I can list Kiwi as a dependency I can release tools which build on top of Kiwi (specifically on top of the instance of Kiwi someone is already using to test their app). When Kiwi is distributed as a framework I either have to ask the end user to manage more complex linking (and resolve version conflicts manually) or embed a redundant copy of Kiwi into my tool (and probably rename it to avoid name conflicts when linking). This has already been a mess with frameworks which repackage the popular networking libraries, I see no reason why Kiwi should be different or encourage a problematic pattern.

[allending]

Persuasive arguments Jonah. I can tell when I'm wrong. Lets go for cocoapods then since there hasn't been any data in the form of a developer that does not want to use it.

On Jan 10, 2013, at 1:02 PM, Jonah notifications@github.com wrote:

I have a few arguments which make me favor CocoaPods.

While downloaded frameworks can contain version information and references to their origin it is less obvious than the convention of a podfile. As a developer joining a project I want it to be easy to identify which release of Kiwi the project uses, if it is up to date, and where it was obtained from (i.e. from allending or someone else's fork).

Kiwi is not and will not be the only third party library my application uses. Considering Kiwi in isolation the framework install process doesn't seem hard but I have never seen an app with only one such dependency. Managing multiple dependencies means I will want to use pods for them. Having Kiwi be an outlier from my default process for installing all other dependencies discourages me from using it or leaves me dependent on an unofficial (and possibly out of date) podfile to install it.

I want to be able to write tools which depend on Kiwi. When I can list Kiwi as a dependency I can release tools which build on top of Kiwi (specifically on top of the instance of Kiwi someone is already using to test their app). When Kiwi is distributed as a framework I either have to ask the end user to manage more complex linking (and resolve version conflicts manually) or embed a redundant copy of Kiwi into my tool (and probably rename it to avoid name conflicts when linking). This has already been a mess with frameworks which repackage the popular networking libraries, I see no reason why Kiwi should be different or encourage a problematic pattern.

—
Reply to this email directly or view it on GitHub.

[jonah-williams]

@allending I'm glad we can win you over, hopefully without steamrolling you.

I'll try to make sure I'm up to date with the current state of and work on CocoaPods. For users unfamiliar with pods I'm afraid this does complicate the install process, hopefully we can provide clear guidelines on how to get up and running, or at least refer them to good documentation provided by pods (I know an update to their docs is in the works).

Hopefully anyone who really cannot use pods (e.g. me trying to add some test coverage to a real mess of a project whose config structure might conflict with pods') will be willing and able to deal with a more complex and not recommended manual installation from source. Otherwise if there is real demand for a non-pod install maybe we need to offer both and can have the pod install build and link against a framework you could also install manually.

[supermarin]

Sorry for my late reply. Totally agreed with @jonah-carbonfive

In my opinion, we can try supporting both, or at least major updates in a .framework form.
The main one should be Cococapods, but there are still corporations and newcomers that aren't able to use Cocoapods.

[frosty]

Having CocoaPods as the recommended solution (but still with a manual option if necessary) sounds like a good idea, and seems to be the way that projects like RestKit and AFNetworking are doing it.

I've been starting a new project this week, and trying to mix a couple of non-Cocoapods frameworks (specifically testing frameworks, it seems) with other Cocoapods libraries has caused me no end of issues. In fact, I've wound up doing manual installs of the other frameworks I was using rather than fighting a losing battle. A supported, official Cocoapod installation of Kiwi would be great.

[frosty]

Also, for what it's worth - I've been exploring the various options for iOS testing recently, and a few setup-related niceties have really stuck out to me:

• Cedar's install script adds Project and File templates to Xcode, as well as code completion snippets for common syntax. Really useful for a newbie getting started.
• I really like Cedar's Rakefile for common tasks - e.g. rake uispecs to build and run specs from the command line. However, it currently seems to be a manual process to copy it to your project and modify it so it'll work.
• Calabash has an automated install script that asks you a few questions and sets everything up. A nice user experience.
• I do really like the 'dot' formatting in Cedar's commandline spec runner - very readable output.

[allending]

Updated podspec to point to version 2.0.x. Working on fixing project structure and docs.

[allending]

Initial 2.0.x install guide based on previous CocoaPods guide here: https://github.com/allending/Kiwi/wiki/Kiwi-2.0.x-Installation

[dimsumthinking]

Sigh.

Allen - if you keep improving things at this pace, I'm going to have to rewrite my book.

Great job -

Daniel
On Jan 17, 2013, at 9:11 AM, Allen Ding notifications@github.com wrote:

Initial 2.0.x install guide based on previous CocoaPods guide here: https://github.com/allending/Kiwi/wiki/Kiwi-2.0.x-Installation

—
Reply to this email directly or view it on GitHub.

[jonah-williams]

Fantastic, nice work @allending.

[frosty]

Great work, @allending!

I'm having a few issues after simply following your initial Kiwi 2.0 installation guide, however. It may be something wrong with my Xcode setup, but I followed your guide step-by-step. The only deviation was when Cocoapods warned me:

[!] The target `KiwiUnitTest [Debug - Release]' overrides the `FRAMEWORK_SEARCH_PATHS' build setting defined in `Pods/Pods-KiwiUnitTest.xcconfig'.

I added $(inherited) to my FRAMEWORK_SEARCH_PATHS build setting to get around this. After selecting my test unit target and trying to Test, I get a linker error when building:

ld: warning: directory not found for option '-F-F/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator6.0.sdk/Developer/Library/Frameworks'
Undefined symbols for architecture i386:
  "_OBJC_CLASS_$_SenTestCase", referenced from:
      _OBJC_CLASS_$_KWTestCase in libPods-KiwiUnitTest.a(KWTestCase.o)
      _OBJC_CLASS_$_KWSpec in libPods-KiwiUnitTest.a(KWSpec.o)
  "_OBJC_METACLASS_$_SenTestCase", referenced from:
      _OBJC_METACLASS_$_KWTestCase in libPods-KiwiUnitTest.a(KWTestCase.o)
      _OBJC_METACLASS_$_KWSpec in libPods-KiwiUnitTest.a(KWSpec.o)
ld: symbol(s) not found for architecture i386
clang: error: linker command failed with exit code 1 (use -v to see invocation)

Other Linker Flags for my test bundle target includes -framework SenTestingKit. The directory referenced by the ld warning appears to exist, and contains SenTestingKit.framework.

Is this my problem, or something wrong with the Kiwi setup?

[frosty]

Aha. After a bit of searching, it appears that the issue I'm hitting is the one discussed in this commit: allending@68ae5c0, which looks like it's a Cocoapods issue: CocoaPods/CocoaPods#653

[allending]

Started work on revised 2.0 docs - https://github.com/allending/Kiwi/wiki.

@dimsumthinking sorry ;)

[supermarin]

@allending is this ready for closing? :)