Create an Appropriate Project

The easiest way to add unit testing support in Xcode 4 is to create a project that uses the Cocoa or Cocoa Touch frameworks, such as a Cocoa or iOS application. When you select an appropriate project and click the Next button, you should see an Include Unit Tests checkbox.

When you select the Include Unit Tests checkbox, Xcode adds a unit test bundle target and a unit testing class to your project. Xcode also does most of the setup work for you. It configures the necessary build settings for unit testing and adds a target dependency so your application target builds when you build the unit test target.

Running Unit Tests After Building Your Project

Adding a unit test bundle when you create an Xcode project takes care of most of the build settings for you. There is one build setting you may have to setup manually. If you want Xcode to run your unit tests when you build the project, you must set the Test After Build build setting to YES. My Xcode 4: Accessing Build Settings post has detailed information on accessing build settings.

Adding Unit Test Classes to Your Project

While Xcode adds a test case class to your project when you create a new project and select the Include Unit Tests checkbox, you’ll eventually need to add more classes for unit testing. Choose File > New > File to add a unit testing class to your project. Select either Cocoa under Mac OS X or Cocoa Touch under iOS on the left side of the New File Assistant. Select Objective-C test case class from the list of file templates. Click the Next button. Enter the name of your class in the Class text field. The name of the class is also the name of the file. Click the Next button. Choose a location to save the file. Click the Create button to create the file.

Make sure the class you create is added to the unit test target, not the application target.

If you mistakenly add the unit test class to the wrong target, select the file from the project navigator and open the file inspector by choosing View > Utilities > Show File Inspector. Use the checkboxes in the Target Membership section to ensure the unit test class is a member of the unit testing target, not the application target. 

Configuring Your Scheme for Testing

Click the name of the scheme in the Scheme menu and choose Edit Scheme to open the scheme editor. Select the Test step from the left side of the scheme editor.

The scheme editor allows you to choose a build configuration to use for unit testing, the debugger to use to debug unit tests, and the unit tests to run. Xcode is setup initially to run all unit tests.

Running Unit Tests

Xcode provides three ways of running unit tests. If you set the Test After Build build setting to YES, choosing Product > Build for Testing builds your project and runs the unit tests. The results of the unit tests appear in the build results window, which you can access from the log navigator. Choose View > Navigators > Show Log Navigator to show the log navigator. Select a build from the log navigator to show the build results window. 

The second way to run your unit tests is to choose Product > Test (or click the Run button and choose Test). When you choose Product > Test, Xcode builds your project and runs the tests. Use the log navigator to view the results of the unit tests. The final way to run your unit tests is to choose Product > Perform Action > Test Without Building, which runs unit tests without building the project.

Adding Unit Test Support to an Existing Project

To add unit test support to an existing project, you must add a unit test target to your project. Select the name of your project from the project navigator to open the project editor. Click the Add Target button at the bottom of the editor. Select the Other group under either Mac OS X or iOS. Select Unit Testing Bundle (either Cocoa or Cocoa Touch) from the target list.

Click the Next button. Enter a name for your target in the Product Name text field. Click the Finish button to finish creating the unit test target.

Adding a unit test target to an existing Xcode project requires more setup work than creating a new project does. You must add a target dependency to the unit test target. You also must configure build settings for the unit test bundle.

Adding Target Dependencies

Adding a target dependency allows Xcode to build your application when you build the unit test target. Select the unit test target from the project editor. Click the Build Phases button at the top of the project editor. Click the disclosure triangle next to the Target Dependencies build phase. Click the + button to add a dependency. Select the application target from the target list.

Configuring the Unit Test Bundle

If you are unit testing an application, you must configure the unit test bundle. There are two build settings you must configure: Bundle Loader and Test Host. The Bundle Loader build setting is in the Linking collection, and the Test Host build setting is in the Unit Testing collection. You must set the value of these build settings to the location of the application’s executable file. For an application named MyApp, the value of the Bundle Loader and Test Host build settings would be the following:

$(BUILT_PRODUCTS_DIR)/MyApp.app/Contents/MacOS/MyApp (Mac)

$(BUILT_PRODUCTS_DIR)/MyApp.app/MyApp (iOS)

iOS applications running in the simulator should leave the Test Host build setting blank. The simulator does not support application-hosted unit tests. If you set the Test Host build setting, you will get a warning when building the unit testing target and the tests will not run.

https://developer.apple.com/downloads/index.action

You can also use this URL to download older versions of Xcode.

If you don’t have an ADC account, you will need to sign up for one to download Xcode from the URL I listed. You can get an ADC account for free.

You can tell Xcode not to open the welcome window by deselecting the checkbox at the bottom of the welcome window. Suppose you deselect the checkbox and decide later you want to open the welcome window. How do you open it?

In Xcode 4 choose Window > Welcome to Xcode to open the welcome window.

Override pyglet’s on_resize() method for the window and make a call to glOrtho(). The following code provides an example of creating a custom-sized orthographic projection:

@window.event

def on_resize(width, height): 

	glViewport(0, 0, width, height) 

	glMatrixMode(gl.GL_PROJECTION) 

	glLoadIdentity()  

	projectionWidth = 24 

	projectionHeight = 16 

	glOrtho(0, projectionWidth, 0, projectionHeight, -1, 1) 

	glMatrixMode(gl.GL_MODELVIEW) 

	glLoadIdentity() 

	return pyglet.event.EVENT_HANDLED

My example copies what the default on_resize() method does, but I supply a custom width and height to glOrtho().

The Xcode Tools Are Packaged in a Single Application

The biggest change in Xcode 4.3 is how Xcode is installed and packaged. Previous versions of Xcode required you to run an installer that installed the Xcode Tools in /Developer or another directory. Xcode 4.3 works like a typical Mac application, where the Xcode Tools appear as a single application in the Finder and install in your Applications folder. Xcode 4.3 is easier to install, uninstall, and update.

Launching Other Developer Tools

Since Xcode 4.3 is a single application you may be wondering how to launch the other tools that come with Xcode, such as Instruments. Launch them from Xcode by choosing Xcode > Open Developer Tool. Choose the tool you want to launch from the submenu. If the tool you want to launch is not in the submenu, choose More Developer Tools. Choosing More Developer Tools takes you to Apple’s developer downloads page, where you can download and install additional tools. If you want to run the Mac OpenGL developer tools that I cover in Chapter 11 of Xcode Tools Sensei, you must choose More Developer Tools and install the Graphics Tools for Xcode package from Apple’s developer page. Download the disk image and drag the applications to your Applications folder.

I don’t know how to add tools to Xcode’s Open Developer Tool menu. I downloaded the Graphics Tools for Xcode package and copied the applications to the Contents/Applications folder inside Xcode’s application bundle, but the applications did not appear in the Open Developer Tool menu. I asked about adding tools to the Open Developer Tool menu on Apple’s paid developer forums, but I have not received any answers.

Update (February 22, 2012)

I received an answer on Apple’s developer forums to my question on adding tools to the Open Developer Tool menu. You can read the solution by reading user18861′s answer to the following question on the Ask Different website:

In Xcode 4.3, where do I put the additional tools?

When the answer mentions /Applications and /Resources, it means the Applications and Resources folders inside Xcode’s application bundle.

Installing Command-Line Tools

Xcode 4.3 does not initially install a copy of command-line tools that allow you to compile programs from the Terminal. You can install the command-line tools from Xcode’s Downloads preferences.

Accessing File and Project Templates

Because Xcode 4.3 does not reside in a Developer folder, you must open the Xcode 4.3 application bundle to access things like Apple’s file and project templates. Select Xcode from the Finder, right-click, and choose Show Package Contents to examine the application bundle. The most interesting directory in Xcode’s application bundle is the following directory:

Contents/Developer

Auto Layout

Cocoa application projects created with Xcode 4.3 enable auto layout. If you don’t want to use auto layout, select the xib file from the project navigator, open the file inspector, and deselect the Use Auto Layout checkbox.

ARC Conversion

In Xcode 4.3 you can use Xcode’s ARC migration tool to convert an existing project that uses garbage collection. Xcode 4.2 could not convert a project to ARC if the project used garbage collection.

Developer Mode

When you build your first project in Xcode 4.3 an alert may open asking if you want to enter developer mode. Entering developer mode lets you do things like debug your project without Xcode asking you for your user account’s password.

Install Mercurial

The source code for pyglet is in a Mercurial repository. If you do not have Mercurial installed on your computer, you must install it to be able to install pyglet 1.2. Installers for Mac OS X and Windows are available at the Mercurial site.

Clone the Repository

Cloning the pyglet repository gives you a copy of the source code so you can install pyglet. Launch the Terminal application, navigate to where you want the source code to reside, and run the following command:

hg clone https://pyglet.googlecode.com/hg/ pyglet

There is a space before pyglet in the last part of the URL. You should see a pyglet folder after cloning the repository.

Install Pyglet

After cloning the repository, it’s time to install pyglet. In the Terminal application go to the pyglet folder and run the following command:

python setup.py install

Now pyglet should be installed and you can start coding.

Install AVbin

Installing pyglet alone has one limitation. It can play only uncompressed audio files. To play compressed audio files, such as MP3 and Ogg Vorbis files, with pyglet, you must install the AVbin library, which is what pyglet uses to play compressed audio. There are multiple versions available for Mac OS X, Windows, and Linux on the AVbin download page. Those of you running Mac OS X 10.6 and later should download a version that supports 64-bit Intel.

After downloading AVbin, you must install it from the Terminal application. Navigate to the avbin folder (the latest name of the folder on Mac OS X is avbin-darwin-x86-64-v8) and enter the following command:

sudo bash install.sh

Running the installation script installs AVbin and lets you play compressed audio files with pyglet.

Create a Cocoa Application Project

When you create a project in Xcode, select the Cocoa Application project, as you can see in the following screenshot:

The Mac OS X version of SDL is written with Cocoa so a Cocoa application project is the closest template to the old SDL project templates. Click the Next button to move to the next step where you name the project.

Deselect the Create Document-Based Application, Use Core Data, and Use Automatic Reference Counting checkboxes. SDL games don’t use Core Data or Apple’s NSDocument class. Automatic Reference Counting is for Objective-C code, which most of you won’t use if you’re using SDL. If you want to unit test your game with OCUnit, select the Include Unit Tests checkbox. My Using Xcode to Unit Test SDL Games Written in C++ post has detailed information on using OCUnit to unit test C++ code.

Click the Next button to move on to the final step of creating a project. Pick a location to save the project and click the Create button. If you want to place your project in a local git repository, select the checkbox to create the repository.

Remove Unwanted Files from the Project

Apple’s Cocoa application project template contains files that are not needed for SDL games. You can remove the xib file and source code files from the project: any files ending in .xib, .m, and .h. In Xcode 4.2 you would delete the following files: main.m, MainMenu.xib, AppDelegate.h, and AppDelegate.m. Select a file and choose Edit > Delete to delete the file from the project. An alert opens. If you click the Delete button, Xcode deletes the file instead of moving it to the Trash. Clicking the Remove Reference button is the safer option. My Xcode 4: Removing Files from a Project post has additional information on removing files from a project.

Add the SDL Framework to the Project

Now it’s time to add the SDL framework to the project. Select the project file from the project navigator to open the project editor. Select your target from the left side of the project editor. Click the Summary button at the top of the editor to see a list of linked frameworks. Click the + button to add a framework. More information on adding frameworks is in my Xcode 4: Adding a Framework to Your Project post. Click the + button to add any additional frameworks, such as OpenGL, SDL_image, and SDL_mixer.

Add SDLMain to the Project

The Mac version of SDL uses two files, SDLMain.m and SDLMain.h, that contain glue code for running SDL code on Mac OS X. The SDL project templates include these files, but in Xcode 4 you must add them to your project. Choose File > Add Files to ProjectName to add the files. After adding the SDLMain files to the project, you can start coding.

Add Search Paths

When I tried to build a SDL project with Xcode 4, I got a build error saying that the file SDL.h was not found. The solution was to add the following search path to the Header Search Paths build setting:

/Library/Frameworks/SDL.framework/Headers

You may also need to add a search path to the Framework Search Paths build setting, but I didn’t need to add a path. You may also need to specify additional search paths if you use additional frameworks, such as SDL_image and SDL_mixer. My Xcode 4: Accessing Build Settings post has detailed information on accessing build settings in Xcode 4.

Copy the SDL Framework to Your Application Bundle

The SDL Xcode project templates copy the SDL framework to your application bundle. Copying the framework to the application bundle allows someone to play your SDL game without having SDL installed. If you want the SDL framework added to your application bundle, add a Copy Files build phase to your target and add the SDL framework to the build phase.

1. Select the project file from the project navigator to open the project editor.
2. Select the target from the left side of the project editor.
3. Click the Build Phases button at the top of the editor.
4. Click the Add Build Phase button at the bottom of the editor.
5. Choose Add Copy Files from the menu.
6. Drag the SDL framework from the project navigator to the table in the Copy Files build phase.
7. Choose Frameworks from the Destination menu.

If you have additional frameworks to copy to the application bundle, repeat Step 6 for those frameworks. Don’t copy Apple’s frameworks to the application bundle; every Mac has Apple’s frameworks installed. Only copy third-party frameworks, such as SDL_image and SDL_mixer.

Configuring a repository is not difficult in Redmine. Create a project, go to its Settings section, and click the Repository tab. But the instructions to configure the repository are misleading for local git repositories. They tell you to enter the path to the repository. If you enter the path to your local git repository, such as the following:

/path/to/repository

You will get a 404 error when you try to access the repository in Redmine. You must enter the path to the repository’s .git folder for Redmine to be able to access it.

/path/to/repository/.git

If you enter the wrong repository path, discover the 404 error, and go back to correct the error by adding .git to the path, you will notice that Redmine does not let you modify the repository path. You must delete the reference to the repository and recreate it.

Click the Delete button, which is in the bottom right corner of the screenshot, to delete the reference to the repository. After deleting the reference, choose a version control system from the SCM menu and reenter the path to the repository.

Accessing the Contextual Menu

The first step to adding an item to a text view’s contextual menu is to access the menu. You can access NSTextView’s default contextual menu using the menu: method.

IBOutlet NSTextView* textView;

NSMenu* textViewContextualMenu = [textView menu];

Adding a Menu Item to the Contextual Menu

After you get access to the contextual menu, call NSMenu’s addItemWithTitle: method to add a menu item to the contextual menu. You must supply three pieces of information: the name of the menu item, the action, and the keyboard equivalent for the menu item. The action is the method that gets called when the user chooses the menu item. The following example adds a Tags menu item to the contextual menu with no keyboard equivalent:

- (IBAction)createTag:(id)sender;

NSMenuItem* tagsMenuItem = [textViewContextualMenu addItemWithTitle:@"Tags" action:@selector(createTag:) keyEquivalent:@""];

If you want to place a menu item in a specific place in the contextual menu, call NSMenu’s insertItemWithTitle: method. This method works similarly to the addItemWithTitle: method, but there is an additional argument to specify: the index (location in the menu) where you want to insert the menu item.

Adding a Submenu

Sometimes you need to add a submenu to a menu item. In the example I’ve been using in this article, you may decide to add a menu of tags as a submenu of the Tags menu so the user can add a specific tag. Call the contextual menu’s setSubmenu: method to add a submenu. Supply the menu to add and the menu item where you’re adding the menu. The following example adds a menu of tags to the Tags menu item:

IBOutlet NSMenu* tagsMenu;

[textViewContextualMenu setSubmenu:tagsMenu forItem:tagsMenuItem];

The example assumes you created a menu in Interface Builder. Add a NSMenu object to the xib file, and add items to the NSMenu object. Creating a menu in Interface Builder is generally easier than creating a menu programmatically, but you can create the menu in your source code if you want. Refer to the NSMenu Class Reference, which is part of Apple’s documentation, to learn more about creating a menu in code. Searching for NSMenu in Xcode’s documentation window should be enough to find the class reference.

Before You Trace

User Interface recording requires the Enable access for assistive devices checkbox to be selected in the Universal Access section of Apple’s System Preferences. The System Preferences application should be in your Applications folder.

User Interface Instrument Results

When you finish a trace with the User Interface instrument, it shows the following information for each event:

• Sample number.
• A thumbnail image of where the event happened.
• Triggers, whose purpose escapes me. For me it always shows an image of a menu with Triggers as the menu choice.
• The type of event, such as mouse button down, mouse moved, and key down.
• Key, which tells you the key that was pressed for a keyboard event.
• Title, which is the title of the view where the event occurred: window, view, control, menu, etc. 
• Location, which tells you the location of the event. Mouse button events are the most common events to have a location.

Don’t worry if you see lots of samples with blank values in the Key, Title, and Location columns. That’s normal behavior. In the track pane mouse events are blue, keyboard events are green, and system events are yellow.

Replaying what the User Interface Instrument Recorded

To replay a sequence you recorded, you must first finish a trace by clicking the Stop button. The Record button now has the title Drive and Record. Click the Drive and Record button to replay the recording. Instruments creates a new run and replays the event sequence.