Xcode 6 is a great environment to develop and test Cocos2d-x games. In terms of functionality and stability as an IDE for C++ development and testing, I think it is comparable to Visual Studio and it is significantly better than Eclipse.
Below is a quick start on how to get Xcode up and running. After the quick start you will find lots of details about Xcode.
Quick Start
1) Signup for the Apple Developer Program.
2) Download and install Xcode using the Mac AppStore.
3) Download and unzip Cocos2d-x.
4) Open Terminal and then change into the unzipped Cocos2d-x directory.
5) Setup Cocos2d-x by executing python setup.py from within the unzipped Cocos2d-x folder. You will need to do this so that you can use the cocos command line tool to create a new project.
6) Create a new Cocos2d-x project by executing:
cocos new MyGameName -l cpp -p com.myCompany.gameName -d PathToSaveMyGame
7) Open Xcode and then open the project located at: MyGameName/proj.ios_mac/MyAppName.xcodeproj
8) Press the button that looks like a play button to build and run your app. Note the dropdown list boxes to the right of the play button to select either the MyAppName-mobile (iOS) or MyAppName-desktop (Mac) target. You can also select which device to run on next to that. e.g. a simulator or a device connected via USB cable.
9) Setup your user account by using the menu Xcode -> Preferences -> Accounts and enter your information. More info about setting up your signing identity, app IDs and provisioning profiles can be found here.
10) Download and install additional simulators or documentation by using the menu Xcode -> Preferences -> Downloads and selecting what to download and install.
Details of the Xcode 6 user interface
There are a lot of details to understand when configuring an app for testing and eventually archiving it and uploading it to the app store. I will now attempt to cover the aspects and settings that are important to know to build, test, archive, and publish an app.
The Navigators
The left side of the Xcode app is the default location of what are called navigators. Sometimes you may accidentally hide the navigator. If this happens, in the main menu of Xcode go to View -> Navigators -> Show Project Navigator to get them back. If the Run button and entire toolbar are not visible, you can click on View -> Show Toolbar to get the toolbar back.
Xcode has the following types of navigators.
Project – Very useful. Shows a list of folder groups and folder references of class files and resource for the project.
Symbol – Have not needed to use this much. Shows the symbols that are used in your app.
Search – Very useful. Used to search through class files and resources in your project.
Issue – Very useful. Shows static analyze and build warnings and errors.
Test — Shows information about your app tests.
Debug – Very useful. When debugging an app, shows the symbol call tree and some other useful stuff.
Breakpoint – Shows a list of breakpoints that are currently defined in your project.
Log – Shows the list of console logs from previous runs of your app.
Changing Views
In the upper right corner by default there exists eight buttons. These buttons are shown here in the following image.
On the left side there are the three Editor buttons. Starting from left to right, the first button sets the standard editor view that you will use most of the time. Alternative views are the next two buttons.
The overlapping circle looking button changes the view to the assistant editor which enables viewing the interface .h file and the implementation .m file side by side. The third button sets the code compare view that enables a two column view to compare your currently selected class to previous git source control commit.
On the right side are the three View buttons. From left to right the first button enables visibility of the navigator on the left. The second button toggles visibility of the console log and debug info on the bottom of the app, and the third button toggles visibility a properties/utilities view on the right of the screen.
The most useful aspect of the properties/utilities side view that I have found is identifying and changing if a class file or resource is part of a target or not. Try clicking on a .m or .cpp class file and then enable the utility side view. You might have to scroll up or down to see it, but there is a section titled Target Membership. This is really useful to check which target a resource or class implementation file belongs to.
For example, you might see an image file or audio file in your project navigator, but when you run your app if it is not part of a target then it will not be copied into the app bundle, and as a result your app code will not be able to load the resource.
Project Settings
Xcode 6 enables having settings that apply to the entire project and also settings that only apply to specific targets. To view the project settings, click on the app name at the top of the project navigator view. You should then see something similar to the following image. However, I have added a second target to this project as well as duplicated the Release configuration and named the copied configuration with the name Distribution.
It is a good idea to always create a Distribution target for apps you intend to publish. Then in your build settings you can configure the code signing of the Distribution target to be the App Store distribution provisioning profile and the code signing for Release configuration can be set to the test provisioning profile or an ad hoc provisioning profile.
It is important to ensure then that any settings you change for the release are also applied to the Distribution configuration so that the only difference between the Release and Distribution configurations are the code signing. You could even wait to copy the release configuration until you have configured it for what you think will be a stable setting and then copy it and create the Distribution configuration with the correct code signing.
One other important thing to note is that you can configure build settings for the project, but the target build settings can override the project build settings.
Target Settings
Target settings are settings that apply only to a specific target.
What is a Target?
A target is basically a specific build of an app. Most of the time I have applied settings at the target level. For example, you might decide to create a free version and a paid version of your app. A simple way to do this is to right click on your existing target and click duplicate. This will create a duplicate of the original target. You can then click slowly on the copied target name twice to highlight it and then rename it to something appropriate, such as SampleOpenGLApp-Free.
What is a Configuration?
Each target can have multiple configurations. The two default configurations are Debug and Release. The primary purpose of these configurations is to enable making small changes when building a specific target, such as enabling or disabling the debugger. Another common example is to define NDEBUG and NS_BLOCK_ASSERTIONS=1 as pre processor macros in your Release and Distribution code so that Assertions are not thrown in code you publish.
Code signing is another type of change that fits well into being defined at a configuration level. As mentioned above, for all of the apps that I create, after I have setup the Release configuration for a project I duplicate it and call the new copy Distribution. I then change the code signing in the Distribution configuration so that it uses the provisioning profile for Apple App store distribution. It is also necessary to change the Archive scheme setting (discussed below) to use this configuration for the specific target (more information about that is provided below in the Schemes section of this article.
General Tab
The General tab is visible when you have a specific target selected. These settings are specific to each target. Here you can set the version number, app identifier, iOS version deployment target, app Icons, splash screens and other settings.
Capabilities Tab
The Capabilities tab is where you define specific capabilities, such as Game Center, that your app requires.
Info Tab
The Info tab displays the info.plist property list file for the specific target that is selected. The info.plist file name can be changed and the specific name is defined in the build settings for each target as the Info.plist File property. Each configuration within each target can optionally have a different info.plist file.
Build Settings Tab
The build settings for each target contain a lot of preprocessor and compiler settings. The following are some that I think are important to understand.
Code Signing Identity – You must set this to your iOS Team Provisioning Profile or some other valid provisioning profile in order to test your app on a physical device. You also must assign a distribution profile to a release or distribution Scheme in order to publish an app either ad hoc or via the Apple App Store.
User Defined Settings – User defined settings enable defining specific things for each target. For example, if you click on Add Build Setting in the bottom right corner of the build settings and add a user defined build settings you could then add something like FREE_VERSION and assign it the YES value. Then in the app you can use the #ifdef preprocessor commands in your app to add conditional build code to alter the build so that one target will build a normal version of your app and one target will build a paid version of your app.
iOS Deployment Target – While this is a setting that can more easily be set in the Summery tab, it is worth noting that this is the minimum iOS version that your app will run on. So if you wanted to set this to 6.0, then you app would be available to run on devices that meet your required device capabilities from the Info tab and have at least iOS 6.0. You should of course have to test on all major versions from 6.0 to the current version to ensure your app behaves as expected.
Base SDK – This is the software development kit that will be used to build and package your app. This is different from the iOS Deployment Target version. It is a good idea to have the latest version of the iOS SDK before publishing your app and set the Base SDK to that version. The default setting is Latest Version, so it should automatically set this to the most recent version you have installed.
Build Phases Tab
The Build Phases Tab is primary used to configure library linking and enables reviewing which resources will be added to a build.
The two most useful features in the Build Phases Tab are the Link Binary with Libraries and the Copy Bundle Resources.
The Link Binary with Libraries enables adding specific frameworks or libraries to your app. For example, if you wanted to add Game Center, you would go to this tab, expand the Link Binary with Libraries and then click the small plus sign in the bottom left corner and select the GameKit.framework to add it to the currently selected target.
It is important to note that this only adds it to the currently selected target. It also strangely adds it to the top of your project navigator view. After adding a framework, drag it down to the Frameworks group folder and then check the target membership in the utility side view discussed in the changing view section above. If you have multiple target, you can choose which target binaries the framework should linked to.
The Copy Bundle Resources allows reviewing all of the resources that will be added to your app bundle when it is packaged. This is a semi-useful way of reviewing your resource bundle before packaging your app.
Schemes
Schemes are used to manage which target configurations to use in specific scenarios. The scenarios for each Scheme are run, test, profile, analyze and archive. I am not sure if scenario is the official name for these, but calling them scenarios seems to make sense to me.
In the Xcode menu, you can click on Product -> Manage Schemes to view the projects schemes. Scheme names are auto created from the target names, so if you want to change their names you can change the target names, delete the schemes in the scheme manager and then auto create new schemes. In the scheme manager you can double-click on a scheme name to view the scheme details. It is here that you will want to set which build configuration is used in each scenario.
If you are not using unit tests and advanced diagnostics, then the Run and Archive scenarios are the most important to you.
The Archive scenario should be set to the build configuration that has the desired distribution code signing. I set this to the Distribution configuration that I created in the Project Settings section above.
For the Run scenario, I initially set this with a configuration of Debug and change between the LLDB and GDB debuggers as needed. After the project becomes more mature, I change the Run scenario to use the Release build configuration and disable the debugger by selecting None from the drop-down list box to select the debugger.
When running your app from using the toolbar, if you hold down the Run button a list box will pop up and you can choose which scenario of a specific scheme to execute. The options are Run, Test, Profile, and Analyze which map back to those defined in for each Scheme.
Debugging an App
Xcode comes with LLDB. With it one thing you can do is set break points in your app by clicking to the left of a line of code.
When a breakpoint is reach during debugging your code, on the left side you see the threads that are active and where in the call tree the app was interrupted.
On the toolbar at the bottom of the class editor view and above the debug area there are six small buttons. The first shows and hides the debug output. The second blue tag looking button enables or disables all breakpoints.
The third button is the continue button. Then comes the step over, step into and step out of buttons. These control the debug flow. You can press the play button to continue the app execution, the step over bent error button to continue to the next line of code in the current code block content, the step into down arrow to step to the next line of code (next line might actually be lower level library code or even assembler sometimes), and the step out of button up arrow steps you out of code and back up to the code block context you previously stepped into.
The two view buttons to the right side of the toolbar are worth mentioning. Try clicking on them to see how they change the debug view.
Profiling an App
Profiling enables running an app on the device or in the simulator and measuring performance related aspects of the app as well as testing for bad code that is causing memory leaks or zombies to be created.
It is important to assess the performance and memory management behavior of an app before publishing. It is also a good practice to periodically utilize Instruments during the development of an app to catch problems and deal with them sooner than later.
If you click and hold on the Run button and then select Profile, you will build your app and if it builds with no errors then the Instruments app will launch. The following image shows the dialog Instruments presents after choosing to profile your app.
Instruments provides several templates that enable profiling your app to identify things like if your app has any memory leaks, zombies, or how time efficient certain modules of your code are.
To see Instruments in action, try selecting the Leaks template and then click profile.
You can then enable or disable automatic snapshots or change the frequency of when snapshots are taken. Each snapshot effectively checks to see if any memory has been leaked.
In the upper left corner you can click on Leaks and this will then change the details table below to show what objects were leaked and what code was responsible.
On the top center of the Instruments app try clicking on the third button above the title View to enable the right side drill down view.
Now click on one of the leaked objects and you can drill down into the code to see what caused the leak.
Static Analyzer
The static analyzer tool that is built into Xcode is a great way to quickly analyze the static code of your project to identify potential issues. You can run the static analyzer by clicking and holding down the run button in Xcode and then select Analyze.
After the static code analyzer completes, click on the triangle with an explanation mark in it at the top of the navigators panel on the left side of Xcode to view the output of the static analyzer. This is the same location where compile warnings and error are displayed. Review the results and take appropriate action to fix any issues that were identified.
Getting Ready to Publish an App
Before you can publish an app, you will need to create an App ID, provisioning profile, and an iTunes Connect profile for your app and change the status of your app in iTunes Connect to Waiting For Upload.
This section provides the the step-by-step process for creating an App ID and provisioning profile and then walks through the process of creating a profile for an app in iTunes Connect.
Creating a new App ID and provisioning profile
1) In a web browser go to http://developer.apple.com, click on Member Center, login with your developer account credentials, click on Certificates, Identifier and Profiles, click on App IDs and then create a new App ID for the app you desire to publish.
2) After creating the new App ID, in the Provisioning Portal, click on Provisioning and then click on the Distribution tab and then click on the plus button in the upper right corner to create a new provisioning profile for your app.
3) Select if the app is being distributed via ad hoc or though the Apple App Store. Enter a profile name for your reference and then select the same App ID you created above.
4) If the app is for ad-hoc distribution select the devices that you previously setup as part of your total of the 100 ad hoc devices you can distribute to.
5) Click the Submit button.
6) Click on the distribution tab again. If the status of your provisioning profile is not active, wait several seconds and then click on the distribution tab again.
7) When the stats of your provisioning profile becomes active, download it and then drag it onto the Xcode icon in your Dock.
Apple has updated Xcode to be able to create an app id and provisioning profile from within Xcode. More info can be found here about how to do that.
Creating a new iTunes Connect App Profile
I recommend using the current version of the Safari web browser when creating your app profile in iTunes connect. For some reason, when I have used the current version of Firefox or Chrome to create a new app profile the drop down list boxes to select the primary and secondary app category do not function correctly.
1) Logon to iTunes connect with your developer account credentials.
2) Select the default language that you would prefer to use to manage this app in iTunes connect.
3) Enter the unique App name that you have the right to use. It can be up to 255 characters long.
4) Select the bundle ID that you created in the provisioning portal for this app.
5) Click continue.
6) Select the date that you desire your app to become available in the Apple App Store. If your app is not approved by Apple’s app review team before this date, then it will be released after Apple approves your app. You can also select if you want to provide a discount to educational institutions and if this app will be sold using Apple’s B2B selling platform.
7) Enter the version number for this App. This version number should be set to match the version number you assigned in the application settings for the specific target. Here you also must enter the copyright ownership of the app and the primary category of the app. It is a good idea to also add a secondary category for your app if one is applicable.
8) Each app must have an age rating assigned to it. To assign an age rating, select the radio buttons next to each content category based on what content is in your app. The age rating will automatically update the radio buttons based on what content is in your app.
9) Enter a description, key words, support email and marketing and support websites for your app. You can also add a link to a privacy policy.
10) To save your app you must upload a 1024×1024 png or jpg file for the app icon and one 960 x 640 or 640 x 960 pixel iPhone screenshot or one 2048 x 1536 or 1536 x 2048 iPad screenshot. Other screenshot sizes include iPhone 5 (640 x 1136) 4”, iPhone 6 (750 x 1334) 4.7”, and iPad 6 Plus (1242×2208) 5.5”.
The screenshot images do not need to be just a screenshot of your app. They should market your app but also accurately convey what it is that someone will be downloading. You can and should add five iPad and five iPhone images for each display size. You can even add a video to showcase your app. The images can be updated until the app is approved by apple. After that, you need to create a new version and submit it to app for review to change the icon image.
11) After saving your newly created app, you can take up to 120 days to configure Game Center, In App Purchase, App Store Language Localization, and other settings in iTunes Connect as you build your app.
12) When you are ready to upload your app, the next step is to click on the blue Ready to Upload Binary button shown in the following image. It should be noted that after you submit your app to Apple and they approve it, you cannot change the App icon, app name, key words, add localization descriptions for additional countries, and several other details about your app unless you create a new version and upload that app for review. It is a good idea to review the iTunes Connect FAQs page by clicking on the link at the bottom of iTunes Connect web application and check out under Manage Your Applications link to see the details of the different statuses an app can be in and what you can and cannot do during each app status.
13) An important legal issue is determining if your app uses cryptography and if so does it comply with the applicable laws relating to selling and exporting an application that uses cryptography. Also, there are important questions that you should get legal advice on regarding if your app uses third party content and if your app uses the advertising identifer.
14) After answering the questions in step 13, click continue and you should be ready to upload your archived app to the Apple App Store.
Archiving and Publishing an App
Archiving an app is a necessary step before you can publish it to the Apple App Store or distribute it via ad hoc or within your company if you have an enterprise developer agreement with Apple.
The first thing to check is that the bundle identifier, bundle display name, and other app info settings are as desired. To do this, click on the target of the app and then click on the info tab.
I needed to overwrite the Bundle identifier and Bundle display name with the settings shown in the following image. Note that the Bundle display name is the name that will be seen under the icon of your app when it is installed on an iPhone, iPod, or iPad.
You should also review the other settings here to verify that the values are as you intend them to be.
Next review the scheme settings for the target that will be archived and ensure that the configuration in the scheme for the Archive scenario has the correct code signing assigned to it in the build settings of the target.
For example, I set Distribution for the scheme of the target that I want archive and publish since that is the target configuration I want to archive.
Then go to the build settings, click on the desired target, click on the build settings tab, and then scroll down to the code signing. For the Distribution configuration in the code signing, I verify that the desired distribution provisioning profile is selected for the two entries under the Distribution configuration (Distribution and any iOS SDK).
After verifying that the code signing is accurate, from the target selection drop down list box in the toolbar in the top left corner of Xcode, select iOS device. If you do not do this step, then the Archive option is greyed out and cannot be selected.
From the Xcode menu, select Product -> Clean.
In the Xcode menu click on Product -> Archive.
The Organizer should then launch showing the newly archived app.
After archiving a properly code signed app, from within Organizer, you can then choose to validate your app. Validation checks to see if the app has the necessary things to submit it to the Apple App store as well as verifies that you have configured an App ID, provisioning profile, created the app in Itunes Connect, and that the state of the app in iTunes Connect is Waiting For Upload.
Validation is automatically done on an app when you choose Distribute in the Organizer and then choose Submit to the iOS App Store and click Next.
You will then need to select the app and the code signing again before uploading the app to Apple for review if you have more than one app that is in the Waiting For Upload state.
All that is left now is to authenticate with your iTunesConnect user name and password and click next.
Your app will then upload to iTunes Connect. You will then need to login to iTunes Connect and complete the app submission process.