Upgrading cocos2d version

Some time ago I grabbed a latest version of cocos2d from their website and created a project from scratch based on a standard cocos2d template. Today I realized it’s a good time to upgrade it to a new version.

There are some discussions around this topic and different solutions proposed, not all of which fulfill my requirements. I currently have all of my source code (together with cocos2d sources) under source control (SVN) and I use XCode – SVN integration.

So what are my options for a migration:

  1. Grab new cocos2d sources, recreate a project from scratch and copy all existing resources to new location. Sounds a bit clumsy and I don’t want to ruin my SVN repository.
  2. Compile cocos2d project separately and add resulted library as a static library reference. It’s a much better idea, but since compiling to different CPU architectures requires different static libraries it’s not something I like the most.
  3. Use XCode cross-project references and build static libraries on demand as described in a following post: http://www.clintharris.net/2009/iphone-app-shared-libraries/

Cross-project references

I pick option #3 because I consider it as a best option in my scenario. I keep documenting what I am doing while applying these changes physically to my project and I hope that I won’t miss anything.

Here is my current project structure:

project structure

  • cocos2d Sources – contains cocos2d sources that are created from cocos2d project template,
  • Classes – where my game logic resides,

First of all I need to remove my existing cocos2d Sources from my project & SVN repository and replace it with a newest version. I am also going not to download the latest cocos2d sources from a website (like I previously did) but rather grab it directly from a github. This way I would be able to easily upgrade my cocos2d libraries later. I have all the source code on my SVN so I should be pretty much safe in case anything goes wrong.

Making the changes

  1. First of all I need to get the latest version of cocos2d from a github and place it on my XCode Workspace folder.
    $ git clone git://github.com/cocos2d/cocos2d-iphone.git
  2. My new cocos2d sources are now in a XCode Workspace folder so I can remove the sources that are stored inside my project, I am doing it from XCode so my SVN repository will be notified by XCode that those files should be also removed from my repo.
    remove cocos2d sources
  3. I need to do the same for cocos2d libraries target,
  4. Following a post of Clint Harris I need to perform plenty of changes to my current project setup,
    • Set a  Source Tree setting (COCOS2D_SRC) in my XCode preferences and point it to my cocos2d-iphone directory,
    • Add a cocos2d-ios.xcodeproj to my solution, ensuring that Copy items checkbox is not checked (otherwise it will copy all the sources to my project which is something I would like to avoid),cocos2d project cross-referenced
    • Set cocos2d-ios.xcodeproj path type to be relative to COCOS2D_SRC setting I have set earlier,
    • Configure my targets to have a direct dependency on cocos2d libraries from external project,
  5. So far so good, but when I am trying to build a project it shows me plenty of errors,cocos2d plenty of issues
  6. Ok, the problem is that I forgot to tell XCode to search for cocos2d headers in a different location that was stored previously, a small change to my “User header search paths” setting to point it to my $(COCOS2D_SRC) setting and…
  7. Still the same… I am googling for a while and it turns out that there might be a problem with some characters in search paths, mine contains a whitespace which I suspect might be causing this problem. I am moving my cocos2d sources to a different location, rebuilding and…
  8. It’s much better now, I still see a bunch of errors but this is something I expected from the very beginning – I need to update my code to conform to a new version of cocos2d and then commit everything I changed so far.
  9. Edit: after fixing some issues related mostly with some name changes I realized I have some issues with linking my target with static libraries; by dragging necessary libraries from cocos2d-ios.xcodeproject to my target > Link Binary With Libraries I made it work.

Wow, that wasn’t as hard as I expected, but it wasn’t as easy as I got used to in .NET. At least I have everything documented in case I need to do it once more. I hope it can be also helpful for you, if you find this short tutorial useful please leave your comment. If you need more details please reference this very great tutorial by Clint.

Be Sociable, Share!
This entry was posted in iPhone and tagged , , , , , , . Bookmark the permalink. Both comments and trackbacks are currently closed.


  1. Posted September 23, 2010 at 11:46 pm | Permalink

    I’ve actually done this already, and painstakingly documented every bit of the process (and then some). ;)

    I also followed Clint’s tutorial initially for my project but found it outdated in some places when I went through it, so I made my own tutorial.

    Now, all my projects cross-reference cocos2d, and whenever I feel like it I just pull the latest version from git and most of the time, it just works. If not, I know it’s my code I have to fix and it wasn’t due to forgetting to add or remove some of the new or renamed cocos2d files to an existing project.

    • Posted September 24, 2010 at 10:06 am | Permalink

      @GamingHorror thanks for your comment. I haven’t seen your tutorial before and definetely it’s much more detailed than my blog post. I will need to look at your building “lite” version approach because this is something I am also considering for my game. I have plenty of tasks that I want to do in my project setup (like automated build, auto-version incrementing on every commit, building for different environments etc.) but at the moment I need to keep it on my pending items list due to time constraints.

      • Posted September 24, 2010 at 10:43 am | Permalink

        Autobuild & version increments (respectively: getting the build version from perforce’s changelist) are also on my todo list … for many months now.

        For autobuilds I’ve been looking into toolsets that provide such automation (Ant & derivates), but they are complex beasts.

        • Posted September 24, 2010 at 11:03 am | Permalink

          I am also leaning toward some toolsets for automating build process. I do have experience with Ant-like solutions on a .NET/Java platform, but I guess it might be harder to find something similiar for Objective-C. Ideally would be to setup a continuous integration environment, but this sounds like a bit overkill for my project that is build by one man army ;)

    • Posted January 19, 2012 at 6:11 am | Permalink

      An intelligent answer – no BS – which makes a pelnasat change