One time setup

From Pixelwave

1 Prerequisites

This tutorial assumes that you are using a mac with OS X Snow Leopard (v 10.6) installed on it.

You should also have the latest version of Xcode with the iOS SDK. This tutorial was written with Xcode version 3.2.5. If you don't have it yet, grab it from the iPhone developer portal.

Note: These instructions also work well with Xcode 4.x on OSX Lion (10.7).

2 Download Pixelwave

There are two ways to get Pixelwave. You can get the latest build from github or you can download a zipped version of the framework. We recommend using git (if you're familiar with it) if you want to always have the latest version.

Setting up the folder structure

No matter which option you choose though, the first thing you should decide is where to place all of the project files on your hard-drive. You can choose any folder, but since this location will be referenced in several places, make sure to choose a folder that you won't move around too much.

We suggest setting the Pixelwave home directory to /Users/{YourName}/Pixelwave. For brevity's sake we'll refer to the path you chose as {PIXELWAVE} from now on.

So to start, go ahead and make the Pixelwave home directory on your hard-drive. For example, my folder structure looks like so:

2.1 Downloading a zip package

You can always grab the latest stable release of Pixelwave from from http://www.pixelwave.org/download. Once you've aquired the source package, unzip it and place the contents in the {PIXELWAVE} folder you created earier.

2.2 Getting the git repo

If you're the kinda person who loves drinking straight from the bottle this option may be for you. By cloning the Pixelwave repository locally you can easily make sure your code is always up to date. This option is a bit more advanced though, so if you've never used git before you're probably better off getting the zip package from the link above.

So to get the latest version of Pixelwave from github just pop up the terminal and type in:

cd 'directory where {PIXELWAVE} should live'
git clone https://github.com/spiralstorm/Pixelwave

3 Configure Xcode

Before you can start using Pixelwave, there's just one thing you'll need to tweak in Xcode's preferences. So go ahead and boot up Xcode.

Set source paths

Open Xcode's preferences panel (Xcode->Preferences...)
Choose the "Source Trees" tab at the top.
Press the '+' button in the lower-left and add the following item:

IMPORTANT: Make sure you type these exactly as written below

Setting Name: PIXELWAVE_SRC

Display Name: Pixelwave Source

Path: {PIXELWAVE}/Pixelwave

Let's add another source location for PixelKit:

Setting Name: PIXEL_KIT_SRC

Display Name: PixelKit Source

Path: {PIXELWAVE}/PixelKit

4 Try it out

Now that you have the basics set up, it's time to do a test run.

In finder, navigate to the Pixelwave home directory you chose earlier ({PIXELWAVE}).
Navigate to /Samples/HelloWorld/
Launch HelloWorld.xcodeproj
Build and run your project
Within moments you should witness the beauty that is Pixelwave

On the simulator, it looks like this:

If there was some sort of error, scroll down to the troubleshooting section below.

If everything worked it means you are now all set up and ready to start. Nice!

Although the next sections of this article are only optional, we suggest giving them some love and learning how set yourself up with the Xcode Templates and Integrated API docs. You'll thank us later.

5 Install the Xcode templates

Note: There currently only templates for Xcode 3. Xcode 4's template structure is too mysterious at the moment to actually be used by 3rd party developers like us.

So everything is working just dandy and you thought "hey, why not also install the Xcode templates?". Well, you've come to the right place!

The main reason for the previous attempt at a joke was to fluff up this section so it doesn't feel too bad about being so short:

Navigate to {PIXELWAVE}/Xcode3/XcodeTemplates
Double click 'Install.app', and follow the instructions.

Now, when you try to create a new Xcode project the 'Pixelwave' section should be waiting for you in the left pane of the 'New Project' window.

If you want to uninstall the templates at any time just run 'XcodeTemplates/Install.app' again and choose the 'Uninstall' option. (But you already figured that, didn't you?)

6 Get the integrated API reference

If you want to access the online Pixelwave API reference, you can do so at any time by clicking over to http://www.pixelwave.org/api.

Although that's cool, wouldn't it be even cooler to be able to use Xcode's own quick-help and documentation window to get info about Pixelwave classes and functions? We have the technology, and you can too!

A quick peek at the API docs for the PXView class.

So here's how you can get the integrated Pixelwave docset for Xcode:

With Xcode open, pop up the preferences window (Xcode->Preferences...)
Navigate to the 'Documentation' tab all the way on the right.
Press the 'Add Publisher...' button.
Enter the following url: http://www.pixelwave.org/download/com.spiralstorm.Pixelwave-API.atom
Give Xcode a second talk to our server, and when it's done press the newly created 'Get' button for the Pixelwave API reference.
That's it. Enjoy!

Updating the API docs

Whenever we release a new set of API docs, all you'll have to do get it is head over to the same preferences window and let Xcode automatically update the docset. Sweet? Yes!

7 Next Steps

That's it! You completed the one-time setup and are now ready to make some awesome iOS projects. Here are some suggestions for what you should do next:

Create your first Pixelwave project
Read the official Pixelwave manual
Visit the Articles section

8 Troubleshooting

I'm getting an error saying "Pixelwave.h: No such file or directory". WTF?

This error means that Xcode can't locate the base Pixelwave directory. This could be because a) you mistyped the path for PIXELWAVE_SRC or b) that you typed the path just fine, but one of your folders contains a space (' ') in the name. Spaces in path names drive the compiler crazy, so don't to it.

I'm getting an error saying "Argument list too long: recursive header expansion failed at ...".

It means that you either didn't define the Xcode environment variables PIXELWAVE_SRC & PIXEL_KIT_SRC, or you misspelled them.

Still you having problems? Perhaps one of these supercilious questions will get you back on track.

What version of Xcode are you using?

Make sure you have the latest version of Xcode and the iOS SDK. At the very least make sure you have Xcode 3.x or higher.

Did you add the Xcode environment variables?

Make sure you followed the steps in this section.