Enable ARC in a Cocos2D Project: The Step-by-Step-How-To-Guide Woof-Woof!

On April 5, 2012, in idevblogaday, by Steffen Itterheim

http://www.learn-cocos2d.com/2012/04/enabling-arc-cocos2d-project-howto-stepbystep-tutorialguide/

总结:

1.delete the "libs" group in Xcode(only "Remove References")

2."Add Target",then select "Cocoa Touch Static Library",

3.click Next , name library as "cocos2d-library".select it in TARGETS,set "objective-c automatic reference counting" to "NO"；set the Always Search User Paths setting to Yes and set the User Header Search Paths to the somewhat cryptic ./** string.

4.select "Test-ARC" in TARGETS,select the Build Phases tab and expand the Link Binary With Libraries list.

5.add "libs" group into project.remember the Create groups for any added folders radio button is selected and the cocos2d-library target is the only target whose checkbox is checked

6.From the Xcode menu choose Edit -> Refactor -> Convert to Objective-C ARC…. This brings up a dialog where you can select the targets to convert. Select only your app’s target but not the cocos2d-library target. Then click on Check.click Next.Then click save.

While Cocos2D is compatible with ARC, simply enabling ARC in the project’s Build Setting will throw several hundreds of errors in your face. Cocos2D doesn’t provide ARC-enabled project templates. Thus this tutorial about how to enable ARC in a newly created Cocos2D Xcode Project.

While none of these steps are overly difficult, you’ll notice there’s plenty of steps to perform. Unavoidably, and on the off chance you don’t already know, I’d like to recommend Kobold2D to you if you want to write ARC enabled Cocos2D apps. Because none of the steps below, really zero, zilch, nada, niente, keine are necessary to enable ARC in Kobold2D. That’s because it ships with 15 template projects all of which have ARC enabled out of the box. And Kobold2D 2.0 with cocos2d-iphone 2.0 is just around the corner.

Self-advertisment aside, these steps are tested with cocos2d-iphone v2.0 but should also work with cocos2d-iphone v1.1 – but admittedly I haven’t tested the process with the v1.1 version. If you find anything that’s not quite working with v1.1 please leave a comment. Preferably with the solution, that’ll be awesome!

UPDATE: I released a video version of this tutorial:

Install Xcode, Cocos2D, and the Cocos2D Xcode Templates

Let’s first check that you have all the prerequisites. With iOS devices selling like Playboys in the 70s these days, there’s got to be those who haven’t gotten to install Xcode or download Cocos2D yet. And for everyone else this is a version-check and a reminder to upgrade their tools and cocos2d frequently. The latter being particularly simple if you’d been using Kobold2D. Just saying.

1. Download and Install Xcode 4. Now might be a good time to upgrade if you’re not on Xcode 4.2 – because there’s no ARC for you without at least Xcode 4.2.
2. Download Cocos2D and extract the cocos2d-iphone-****.tar file by double-clicking it. The filename varies depending on the cocos2d version.
3. Open Terminal.app and enter:
   ./path-to-cocos2d-iphone/install-templates.sh -f
   

   Note: The path-to-cocos2d-iphone needs to be replaced with the actual path to the cocos2d directory. For example, if you are using Safari and extracted the file cocos2d-iphone-2.0-rc0a.tar where Safari downloaded it, then this command should work for you: ./Downloads/cocos2d-iphone-2.0-rc0a/install-templates.sh -f.
   Note that the leading dot is essential, without it you’ll most likely get a “No such file or directory” error.

   The install-templates.sh script will install the cocos2d-iphone Xcode templates. You have to run this script each time you download a new Cocos2D version to make sure that newly created cocos2d projects use the latest cocos2d version.
   
   The template files are copied to the user’s Developer directory which is~/Library/Developer/Xcode/Templates. This is the directory you want to browse to in Finder if you ever wanted to delete the cocos2d Xcode templates. Perhaps to remove older version files or in case the install script fails with a permission issue.
   
   The -f switch forces the script to replace any existing cocos2d template files, so that you don’t get any errors should you have previously installed the cocos2d Xcode templates.

ARC-ifying the Cocos2D code of the Template Projects

First we are refactoring the Cocos2D code away from your project and into a static library, so that your ARC-enabled code and the non-ARC cocos2d code can work happily together. If you were to enable ARC without separating the cocos2d source code the compiler would not be very happy. The Cocos2D codebase may be compatible but it’s not compliant with ARC, meaning Cocos2D itself is not using ARC and must be compiled with ARC disabled.

The following steps are the same for all Cocos2D Xcode Project Templates. I chose the Box2D template but you can apply the same steps to any of the other templates as well.

1. Open Xcode (duh!)
2. Create a new project, for example by selecting from the menu: File -> New -> Project…
3. Select the desired cocos2d Xcode Template: Box2D, Chipmunk or no physics for either iOS or Mac OS X.
4. Click Next and give the new project an appropriate name and save it anywhere (but remember where).
5. Build & Run the project to verify that it’s working. You never know.
6. Delete the libs group in Xcode. Make sure to select Remove References in the confirmation dialog because you’ll still be needing the files later on, so don’t trash them.
7. Select the Project itself in the Project Navigator. It’s the first entry with the blue document icon in the treeview pane on the left side of the Xcode window. Then click the Add Target button at the bottom, just below the Project/Targets list.
8. In the Add Target template dialog navigate to the Framework & Library group and select Cocoa Touch Static Library respectively Cocoa Library if you develop a Mac application. Then clickNext.
9. Name the library appropriately, for example cocos2d-library. Be sure to deselect both Include Unit Tests and Use Automatic Reference Counting.
   

   Warning: Some recommend to use the -fno-objc-arc Compiler Flag to disable ARC on a per-source-file basis. This is only helpful if you have very few source code files which require this flag where an extra static library target would be overkill. Since you’ll have to add the flag to each cocos2d source code file individually – one-by-one – and there being anywhere between 100 and 150 source files, I strongly discourage going down this road. Plus it will be a maintenance nightmare whenever you upgrade cocos2d.

10. Once created, the cocos2d-library target is selected and the Build Settings pane is shown. You need to navigate the Build Settings to make two changes to the Search Paths section. The easiest way to find these settings is by entering “search” to the search filter textbox in the upper right corner of the Build Settings pane.

    Set the Always Search User Paths setting to Yes and set the User Header Search Paths to the somewhat cryptic ./** string.

    Note: You can edit the User Header Search Paths setting in two ways, one by clicking it twice with a delay between the clicks – this allows you to enter the text directly. Alternatively you can double-click the field which brings up an additional dialog with a checkbox in it. In that case, either enter just a dot and click the checkbox, or enter the full string ./** but do not check the checkbox. Otherwise you might end up with the string ./**/** which will cause compiler errors. Be sure to verify the string is correct after the edit dialog closes, since Xcode might change the string depending on whether the checkbox is checked.

    Warning: The search path ./** is a quick & dirty short-hand for “search the project’s folder and all of its subfolders recursively”. This works fine as long as any header file you create or add to your project does not have the same name as a header file in thelibs folder. For example, you must not add a header file named CCNode.h to your project, because the compiler will be confused which CCNode.h to use – the one from your project or the one provided by cocos2d-iphone. This applies to all files in the path, including those that aren’t referenced by the Xcode project.

11. Select the original target of the project. That means the one that was already there, the one that’s building your app, not the cocos2d-library target you just added. Select the Build Phases tab and expand the Link Binary With Libraries list.
12. Click on the + button at the bottom of the list, select the libcocos2d-library.a file and click theAdd button. This will link the cocos2d library code to your project’s target.
13. Now it’s time to re-add the cocos2d files. Use File -> Add Files to “name-of-project”… to bring up the file dialog. Navigate to and select the libs folder. Make sure the Destination checkbox is unchecked and the Create groups for any added folders radio button is selected. Finally verify that the cocos2d-library target is the only target whose checkbox is checked before clicking the Addbutton.
14. Build and run to make sure everything works now that the cocos2d code was separated into a static library.

Enabling ARC in your project

Now that the cocos2d code is separated from your project’s code, you can use the built-in Xcode ARC conversion tool to update the project template code to use ARC. This will also enable the appropriate Build Settings.

1. From the Xcode menu choose Edit -> Refactor -> Convert to Objective-C ARC…. This brings up a dialog where you can select the targets to convert. Select only your app’s target but not the cocos2d-library target. Then click on Check.
2. Xcode will build your code with ARC enabled and then present you with a wizard that helps you convert the project’s code to ARC. Read the text and click Next.
3. Xcode will show a dialog that allows you to review the changes it is about to make. You can safely accept all of these changes.
4. Build, run and rejoice: Your project’s code is now ARC-enabled!

Cleaning up (optional)

When you created the cocos2d-library target it also added three source code files to the project that you don’t need. You can safely delete (trash) the cocos2d-library group and all the files in it.

You only need to make a small change to the Build Settings of the cocos2d-library target. Locate thePrefix Header Build Setting, select it and press the Delete key so that the Prefix Header setting is empty. Alternatively just keep the prefix header file and only delete the two other files (cocos2d-library.h and .m).

Enjoy your ARC, WOOF, WOOF, GRRRRRR!

This should make it straightforwd for everyone to enable ARC in a Cocos2D project. Of course you can always just get Kobold2D and not concern yourself with these nasty technical things at all.

I hope you enjoyed this tutorial. Please leave a comment if you found any discrepancies, specifically since newer cocos2d or Xcode versions might behave slightly different. I’d also appreciate it if you’d tweet, like or plus-one this article if you liked it. Thank you!