Add Nimbus to your project

This tutorial will show you how to add the Nimbus framework to your project. No previous knowledge of Nimbus is required. Basic Xcode knowledge is assumed.

If you have any trouble along the way please feel free to tweet @nimbuskit or shoot Jeff an email at jverkoey@gmail.com.

Downloading Nimbus

The recommended way to get Nimbus is to use git. git is included with Mac OS X and allows you to efficiently fetch new updates. It is also the only means by which you can make modifications back to the original project.

Open Terminal and enter the following to check out the Nimbus repo:

$ cd ~/path/to/dev/folder
$ git clone https://github.com/jverkoey/nimbus.git

This will download the Nimbus source into the current working directory in a folder titled nimbus. Nimbus uses ARC, which means if you're building an app that doesn't use ARC you will need to enable ARC in your project and disable ARC compilation for all of your other source files.

You may also want to check out Nimbus' submodules. This will check out AFNetworking and JSONKit so that the Nimbus sample applications work.

$ git submodule init
$ git submodule update

Understanding Nimbus' Dependencies

Nimbus is a framework consisting of multiple features that can be individually added to your project. Every feature in Nimbus depends on the Nimbus core. Some features may depend on other features, such as the Photos feature which depends on the Paging Scroll View feature.

Each feature defines its dependencies in a deps file contained within the feature's root folder. Here's the deps file for the Photos feature:

core
pagingscrollview

This means that in order to get the Photos feature to compile correctly you will need to also add the Core and PagingScrollView features.

Prepare your Xcode project

Create a new iOS Xcode project or open an existing project. Within the project navigator on the left hand side, right click on the project root and select New Group:

Name this new group Nimbus; this will be the root group for the Nimbus framework.

Under the Nimbus root group, add another group named Core. Add groups for any other Nimbus modules you intend to use. All Nimbus module dependencies are stored in the deps file within each module

You should end up with a group structure similar to the following:

Add Nimbus source files

Right click the Core group and select "Add Files to "YourProject"..."

Navigate to where you previously checked out Nimbus and open the src/core/src directory.

~/path/to/nimbus/src/core/src/

...and select all the source files (cmd-A).

Make sure the "Copy items to destination group's folder" checkbox is left un-ticked and then Add the files.

Do the same for the other Nimbus modules you wish to add and you should be left with something like this:

Ready to use Nimbus

You can now use Nimbus in your project. If you are using Nimbus throughout your project it is useful to import the header files in your Prefix Header file:

// YourProject_Prefix.pch

#ifdef __OBJC__
   #import <Foundation/Foundation.h>
   #import <UIKit/UIKit.h>
   #import <QuartzCore/QuartzCore.h>
   #import "NimbusCore.h"
   #import "NimbusWebController.h"
#endif

Updating Nimbus

If you want to update to a newer version of Nimbus, pull the changes from GitHub:

$ cd ~/path/to/nimbus/
$ git fetch; git rebase origin master

This will update the Nimbus source files that you have added to your project using the above method. If there are new source files added to the module you updated, then you will have to add these files using the same method as above. It's easy to keep track of newly added or removed files by following the API diffs published with every release.

Next Steps

Now that you've learned how to add Nimbus to your project, try looking through the Nimbus Catalog application found in the examples directory.