CoconutKit is a library of high-quality iOS classes for dealing with view controllers, multi-threading, animations, and more
CoconutKit is a library of high-quality iOS components written at hortis le studio and in my spare time. It includes several tools for dealing with view controllers, multi-threading, animations, as well as some new controls and various utility classes. These components are meant to make the life of an iOS programmer easier by reducing the boilerplate code written every day, improving code quality and enforcing solid application architecture.
Most of CoconutKit components are not sexy as is, but rather useful. Do not be freaked out! These components are meant to make you more productive, less focused on debugging, so that you can spend more time working on the design of your application (if you have a great designer at hand, of course). Give CoconutKit a try, your life as an iOS programmer will never be the same afterwards!
CoconutKit is distributed under a permissive MIT license, which means you can freely use it in your own projects (commercial or not).
CoconutKit provides your with several kinds of classes covering various aspects of iOS development:
You can download CoconutKit from the official github page, both in binary and source forms. A companion repository exists for easy installation using CocoaPods, but you do not need to check it out directly.
You can also directly checkout the git repository. Note that there are submodules you must update using the
git submodules update --init command.
CoconutKit is and will stay free. However, if you enjoy using it, you can support the countless hours of work that are invested into its creation. Thank you in advance!
If you enjoy the library, hortis and I would sincerely love being credited somewhere in your application, for example on some about page. Thanks for your support!
Check out the CoconutKit source code repository by visiting the official project github page, open the workspace and either run the
CoconutKit-demo or the
CoconutKit-dev targets. The result of running those targets is the same, the only difference is that
CoconutKit-demo compiles and builds the CoconutKit library source code before using the resulting binaries, whereas
CoconutKit-dev includes and compiles all libary sources as part of the project itself.
When designing components, I strongly emphasize on clean and documented interfaces, as well as on code quality. My goal is to create components that are easy to use, reliable, and which do what they claim they do, without nasty surprises. You should never have to look at a component implementation to know how it works, this should be obvious just by looking at its interface. I also strive to avoid components that leak or crash. If those are qualities you love to find in libraries, then you should start using CoconutKit now!
You can add CoconutKit to your project in several different ways:
You can grab the latest tagged binary package available from the project download page. Add the
.staticframework directory to your project (the Create groups for any added folders option must be checked) and link your project against the following system frameworks:
If your project targets iOS 4 as well as iOS 5 and above, you might encounter symbol not found issues at runtime. When this happens:
UIKit.framework(click on your target, select Build Phases, and under Link Binary With Libraries set
_objc, then link your target with the ARC Lite libraries by adding the
-fobjc-arcflag to your target
Other Linker Flagssettting
Since CoconutKit 2.0, the easiest way to add CoconutKit to a project is using CocoaPods. The CoconutKit specification file should be available from the official CocoaPods specification repository. If this is the case, simply edit your project
Podfile file to add an entry for CoconutKit:
platform :ios pod 'CoconutKit', '~ '
If the specification file is not available from the official CocoaPods specification repository, use the specification file available in the
Tools/CocoaPods directory. Either add it to your
~/.cocoapods local specification repository (creating the dedicated folder structure), or edit your project
Podfile to tell CocoaPods to use the file directly:
platform :ios pod 'CoconutKit', :podspec = '/absolute/path/to/CoconutKit/Tools/CocoaPods/CoconutKit.podspec'
The specification file has successfully been tested with CocoaPods 0.15.2.
CoconutKit uses a logger to provide valuable information about its internal status. This should help you easily discover any issue you might encounter when using CoconutKit. To enable internal CoconutKit logging:
.staticframework(edit your project debug configuration settings so that the debug binaries are used)
HLSLoggerLevelentry to your project
.plistto set the desired logging level (
Pods.xcodeprojproject settings, adding
-DHLS_LOGGERto the Other C Flags setting for the debug configuration. This setting is sadly lost every time your run
pod installto generate the CocoaPods workspace
HLSLoggerLevelentry to your project
.plistto set the desired logging level (
CoconutKit logger also supports XcodeColors. Simply install the XcodeColors plugin and enable colors when debugging your project within Xcode by adding an environment variable called
XcodeColors to your project schemes. Projects in the CoconutKit workspace all have this environment variable set. If you see strange
[fg sequences in your Xcode debugging console, either install XcodeColors or disable the
XcodeColors environment variable by editing the corresponding project schemes.
After CoconutKit has been added to your project, simply import its global public header file in your project
Some code snippets have been provided in the
Snippets directory (and more will probably be added in the future), both for ARC and non-ARC projects. Add them to your favorite snippet manager to make working with CoconutKit classes even more easier!
To discover what CoconutKit can do, read the project wiki and, once you want to learn more, have a look at header documentation. I try to keep documentation close to the code, that is why header documentation is rather extensive. All you need to know should be written there since I avoid detailed external documentation which often gets outdated. After you have read the documentation of a class, have a look at the demos and unit tests to see how the component is used in a concrete case.
Good documentation is critical. If you think some documentation is missing, unclear or incorrect, please file a ticket.
I sadly have not enough time to develop new features and to refactor existing ones while keeping CoconutKit public APIs unchanged or backward compatible. Sometimes method prototypes or even class names must change, and I cannot afford marking methods or classes as deprecated while still maintaining them. Let's face the truth: CoconutKit is not yet widely enough used to justify the amount of work which would be required.
When updating the version of CoconutKit you use, your project might therefore not compile anymore. In general, you should keep in mind that:
Version 2.0 is a major improvement over 1.x, which means several classes have undergone major changes. As usual, please read the header documentation to find what has changed:
placeholderViewoutlet has therefore been replaced with a
placeholderViewsoutlet collection, and you need to update your code and nib files accordingly. Methods to set an inset view controller now require a new index parameter specifying which inset must be set. Moreover, transition animations are not specified anymore using an enum value, but rather using a class
animatedparameter has also been added to push and pop methods
forwardingPropertiessetting has been removed. If you relied on it, you will need to update your code accordingly
-shouldAutorotateToInterfaceOrientation:implementation, replacing it with
HLSAnimationStephas now been split into
HLSViewAnimationStep(for UIView block-based animation steps) and
HLSLayerAnimationStep(for Core Animation layer-based animation steps). The old
HLSViewAnimationStephas been replaced with
HLSViewAnimationfor UIView block-based animations, and a corresponding
HLSLayerAnimationhas been introduced. The animations you previously defined by setting transforms on
HLSViewAnimationStepare now created by calling translation, rotation or scale methods on
HLSModelManagerobject and use the corresponding class methods to push it onto a stack for the current thread. Then use the
HLSModelManagercontext-free methods to interact with the store
The workspace file contains everything to build CoconutKit binaries, demos and unit tests.
Several projects are available:
CoconutKit: The project used to build the CoconutKit static library
CoconutKit-resources: The project creating the
.bundlecontaining all resources needed by CoconutKit
CoconutKit-dev: The main project used when working on CoconutKit. This project is an almost empty shell referencing files from both the
CoconutKit-demo: The project used to test CoconutKit binaries against linker issues. When building the demo project, the CoconutKit
.staticframeworkis first built and saved into the
CoconutKit-test: The project running unit tests. This project references files from the
Several schemes are available:
CoconutKit: Builds the CoconutKit static library
CoconutKit-staticframework: Builds the CoconutKit
Binariesdirectory, both for the Release and Debug configurations
CoconutKit-resources: Builds the CoconutKit resource bundle into the
CoconutKit-(dev|demo): The standard CoconutKit component demo
CoconutKit-(dev|demo)-RootStack: A demo where CoconutKit stack controller is the root view controller of an application
CoconutKit-(dev|demo)-RootSplitView: A demo where a UIKit split view controller is the root view controller of an application
CoconutKit-(dev|demo)-RootTabBar: A demo where a UIKit tab bar controller is the root view controller of an application
CoconutKit-(dev|demo)-RootNavigation: A demo where a UIKit navigation controller is the root view controller of an application
CoconutKit-(dev|demo)-RootStoryboard: A demo where a storyboard defines the whole application view controller hierarchy (itself managed using CoconutKit view controller containers). Runs on iOS 5 and above
CoconutKit-test: CoconutKit unit tests
Schemes ending with
ios4 are similar, but with features not available on iOS 4 removed.
CoconutKit is compatible with iOS 4 and later (this will change as old OS versions get deprecated), both for iPhone and iPad projects. Please file a bug if you discover this is not the case.
CoconutKit can be used with Xcode 4.4.1 (iOS SDK 5.1) and above, but is best used with the latest versions of Xcode and of the iOS SDK. Binaries themselves have been compiled using LLVM so that only projects built with LLVM will be able to successfully link against it (linking a project built with LLVM GCC against a library built with LLVM may result in crashes at runtime).
Yes. As long as you use binaries or CocoaPods, no additional configuration is required.
CoconutKit does not use any private API and is therefore AppStore friendly. Several applications hortis developed use CoconutKit and have successfully been approved.
My company, hortis, has a long tradition of open source development. This is one of the major reasons why I started to work for its entity devoted to mobile development, hortis le studio.
When I started iOS development a few years ago, I immediately felt huge gaps needed to be filled in some areas, so that I could get more productive and write better applications. CoconutKit was born.
During the last years, I was able to develop some areas of expertise (most notably view controller management, animations and Core Data). I always try to push the envelope in those areas, and I humbly hope the iOS community will be able to benefit from my experience.
No, CoconutKit currently does not use ARC itself. This will maybe change in a not-so-near future as ARC is adopted.
HLS stands for hortis le studio.
You can contribute, and you are strongly encouraged to. Use github pull requests to submit your improvements and bug fixes. You can submit everything you want, documentation and comment fixes included! Everything that tends to increase code quality is always warmly welcome.
There are some requirements when contributing, though:
CoconutKit-dev project to easily write and test your code. When you are done with the
CoconutKit-dev project, update the
CoconutKit-demo projects to mirror the changes you made to the source tree. New resources must be added to the
Any new public header file must be added to the
CoconutKit-(dev|test).pch file, as well as to the
publicHeaders.txt file located in the
CoconutKit-dev directory. Source files with linker issues (source files containing categories only, or meant to be used in Interface Builder) must also be added to the
bootstrap.txt file. Please refer to the
make-fmwk.sh documentation for more information.
For non-interactive components, you should consider adding some test cases to the
CoconutKit-test project as well. Update it to mirror the changes made to the source and resource files of the
Branches are managed using git-flow:
masteris the stable branch on which commits are only made when a new official release is created
developis the main development branch and should be stable enough for use in between official releases
featurebranches. You should avoid such branches since they might not be stable all the time
If you plan to develop for CoconutKit, install
git-flow and setup your local repository by running
git flow init, using the default settings.
I really would like to thank my company for having allowed me to publish this work, as well as all my colleagues which have contributed and given me invaluable advice. This work is yours as well!
The following lists all people who contributed to CoconutKit:
.staticframeworkcan now built within Xcode, and demo projects build it first as well
-popoverControllermethod has been added to UIViewController so that parent popover controllers can easily be accessed
Feel free to contact me if you have any questions or suggestions:
Thanks for your feedback!
Copyright (c) 2011-2012 hortis le studio, Samuel Défago
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.