How to upgrade an existing project to 3.2.1: (includes some rants)
TL:DR: Check out the repo at https://github.com/NoodlFroot/Test-of-Cocos2d-Upgrade which is a working version of the iOS-Newton template that has been manually upgraded to 3.2.1
0) Commit and backup your project. Move to a new branch. Make another backup to be sure - this will get messy.
Warn your co-developers not to do anything for a while.
1) Download the latest SpriteBuilder from Mac App Store (you can probably work direct from the Cocos2d ZIP - but without a template project the SB examples are useful)
2) Launch SB and create a new project
Rant: Make sure your project name is something 1990s compatible like SBTest321 because "SpriteBuilder - Test - Lib 3.2.1" is a bit too complicated for it
3) Close Sprite Builder
Rant: Don't look at the documentation as that will start showing you the 'good old days' of the installer as it hasn't been updated beyond 3.1 yet....
4) In Finder go to the SB project just created (Rant: It's the folder with the nasty non-standard yellow icon) and drill down to Source/libs - the 104MB folder 'cocos2d-iphone' that is in there is going to replace the nice 3-4MB folder of cocos2d library you used to have.
5) In your current project on its new clean branch: Remove + delete all the cocos2d library code and any search paths you had setup
6) Drop a copy of the folder 'cocos2d-iphone' into your project's folder (let's assume you have a 'libs' folder underneath your SRCROOT for convenience)
7) In XCode drag the cocos2d-ios.xcodeproj into the Libs group where your cocos2d library used to be
8) Open up the Sprite Builder project you made in step (2) in XCode - open the SBTest321.xocdeproj (or whatever yours is called) for reference to the project settings
9) In XCode we now need to match our own projects build settings/dependencies to the Sprite Builder setup
In the project settings
a) Goto build phases and add a 'Target Dependency' on cocos2d (cocos2d-ios)
b) In Build Settings find the Search Paths area and setup the following in the 'Header Search Paths':
$(SRCROOT)/$(PROJECT_NAME)/libs/cocos2d-iphone/cocos2d - recursive
$(SRCROOT)/$(PROJECT_NAME)/libs/cocos2d-iphone/cocos2d-ui - recursive
$(SRCROOT)/$(PROJECT_NAME)/libs/cocos2d-iphone/external/ObjectAL - recursive
If using Chipmunk add these too:
$(SRCROOT)/$(PROJECT_NAME)/libs/cocos2d-iphone/external/Chipmunk/objectivec/include - non-recursive
$(SRCROOT)/$(PROJECT_NAME)/libs/cocos2d-iphone/external/Chipmunk/include - non-recursive
NB: You can ignore the kazmath folder path in the SB project - that folder is empty if it even exists and no longer needed
10) Try and build your project - with any luck you are just getting linker errors (You might want to goto XCode -> Preferences -> General and tick 'Continue Building After Errors' to see everything that is going wrong at this stage to sort out any Header path issues.
You probably have a load of code errors as well to do with the upgrade from whichever version of the library you were on before - depending on how nasty and how core to your project the changes are you might want to sort them out now, or comment chunks out to try and get something running.
11) Lets fix the linker problems: back into your projects 'Build Phases' page: In 'Link Binary With Libraries' you need to add two more:
12) Try another build - hopefully it links this time and you can run and see how much work you have to do to upgrade to the latest library
13) Further issues:
I got some build issues on the test project as I changed simulator type: delving into the cocos2d and Chipmunk project (in Libraries -> cocos2d -> external in the Xcode navigator) and setting Build Active Architecture Only to NO for all settings fixed it.
14) Commit your changes - there will be a lot of extra stuff, and a lot of crud as the cocos2d project folder has a load of intermediate build files in it, and also all the documentation building stuff - to install the latest docs build the 'appledoc' scheme in your updated project. You could get adventurous and delete a load of the stuff in the cocos2d project folder that is obviously not needed - send me a pull request if you have the time to do that.
So it is doable - there are probably simpler ways to do it - I just hacked along trying to make the project setup match the Sprite Builder project one.