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.

What the OpenGL Driver Instrument Does

The OpenGL Driver instrument records OpenGL statistics. Some statistics this instrument records include the following:

• The amount of free video memory.
• The number of textures used.
• The number of buffer swaps.
• The amount of time the CPU waited for the GPU.
• The number of surfaces the GPU allocated.

Obviously OpenGL applications are the ones to benefit from the OpenGL Driver instrument. The OpenGL ES Driver instrument records similar information for iOS applications. The OpenGL ES Driver instrument is available in both the OpenGL ES Driver and OpenGL ES Analysis templates. In most cases you should use the OpenGL ES Analysis template for OpenGL ES profiling.

One thing you’ll notice when you create a new trace document is there is no template for the OpenGL Driver instrument. Pick one of the other templates (Time Profiler and Empty would be good choices for profiling purposes) and add the OpenGL Driver instrument to the trace document by dragging the instrument from the Library to the instrument list. Click the Library button in the trace document window toolbar to open the Library.

Before You Trace

Before you start tracing you must tell Instruments the statistics to show in the track pane and detail view. Click the Info button next to the OpenGL Driver instrument to open a pop-up editor. Click the Configure button to see all the available statistics. Select the checkbox next to a statistic to tell Instruments to show it in the track pane and detail view. The extended detail view shows all the statistics so you should show only the most important statistics in the track pane and detail view.

The screenshot also shows where you set the sampling rate.

Trace Results

Use the Target menu in the trace document window toolbar to pick an application to profile. Click the Record button to start profiling. Click the Pause button to pause recording and see the statistics. The track pane graphs each statistic you told the OpenGL Driver instrument to observe.

The detail view at the bottom of the trace document window has one column for each statistic you told Instruments to show. There is one row in the detail view for each sample the OpenGL Driver instrument recorded. Selecting a sample from the list shows all the OpenGL statistics for that sample in the extended detail view. The extended detail view is on the right side of the trace document window. If you don’t see it, choose View > Extended Detail or click the right button in the View group in the toolbar.

There are three views in Instruments that can help you find the parts of your code that are allocating large amounts of memory: the extended detail view, the call tree view, and the source view.

Extended Detail View

When you select a memory allocation from the detail view, the extended detail view shows the call stack for that memory allocation. Examining the call stack can help you find the function in your code that makes the memory allocation. To open the extended detail view, choose View > Extended Detail or click the right button in the View group in the toolbar.

Call Tree View

The Allocations instrument initially shows the table view, which tells you memory allocation statistics. Switching to the call tree view can help you find where your application allocates memory. Use the jump bar to switch to the call tree view.

To the left of the call tree view is the Call Tree collection of checkboxes. Selecting the Invert Call Tree and Hide System Libraries checkboxes can help you quickly find your code in the call tree view.

Source View

Double-clicking one of your functions from the extended detail view’s call stack or the call tree view opens the source view. The source view highlights the lines of code in the function that are allocating memory and tells you the amount of memory allocated. More information on the source view is available in the Instruments Source View post, but keep in mind that some parts of the post do not apply in Xcode 4.

For more information on Xcode 4 project templates, look at Apple’s templates and read the following articles, which you’ve probably read if you’ve done a Google search for creating project templates in Xcode 4:

A minimal project template for Xcode 4

About XCode 4 Project Template (How To Create Custom Project Template)

Project Template Contents

At a minimum a project template consists of two items: a folder with the extension .xctemplate and a property list file named TemplateInfo.plist. You can also have additional files like icon files, source code files, and xib files in the project template. Place these files and the property list file in the template folder.

The .xctemplate extension defines the folder as a template folder. The name of the folder is the name that appears in the list of templates for the selected category in the New Project Assistant. The name of the folder is the name of the template.

Apple’s Project Templates

I recommend duplicating the TemplateInfo.plist file from one of Apple’s templates and using that copy as your TemplateInfo.plist file. You can find Apple’s iOS project templates in the following location:

Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/Templates/Project Templates

The rest of Apple’s project templates are in the following location:

Developer/Library/Xcode/Templates/Project Templates

Developer is where you installed Xcode 4.

Open the TemplateInfo.plist file in Xcode to modify it. I’m going to cover the keys in the TemplateInfo.plist file later in this post.

Moving the Template Folder

For Xcode to find your project template you must move the template folder to the user templates folder, which is in the following location:

/Users/Username/Library/Developer/Xcode/Templates/Project Templates/GroupName

You may need to manually create some of the folders in the path to the user templates folder. GroupName is the name of the category on the left side of the New Project Assistant. You can create your own group name or use one of the built-in names. Your project template will appear in the GroupName category.

TemplateInfo.plist Keys

The TemplateInfo.plist file has the following keys (this may not be an exhaustive list) for project templates:

• Ancestors
• Concrete
• Definitions
• Description
• Identifier
• InjectionTargets
• Kind
• MacOSXVersionMin
• Nodes
• Options
• Platforms
• Project
• SortOrder
• Targets

Your template does not have to use all these keys. The data type for the keys is usually one of the following: Array, Boolean, Dictionary, or String.

Ancestors Key

The Ancestors key is an array of strings. The strings are the identifiers of the project templates your template inherits from. If your template has no ancestors, you can ignore this key.

Suppose your template inherits from Apple’s Cocoa Application template. You want the same options the Apple template has to create a document-based application, to use Core Data, and to add a unit testing bundle. In this case you would need to inherit from Apple’s document-based application, Core Data application, and CoreDataSpotlight application templates. You would add the following ancestor values to your template:

com.apple.dt.unit.cocoaDocumentBasedApplication

com.apple.dt.unit.coreDataApplication

com.apple.dt.unit.coreDataSpotlightApplication

Concrete Key

The Concrete key is a Boolean value. You must set the Concrete key to YES for your template to appear in the New Project Assistant.

Definitions Key

The Definitions key is a dictionary. This key allows you to add comments, includes, and code to source code files. It also allows you to create groups from files or folders in an Xcode workspace. If you use the Definitions key to create groups, you must also have a Nodes key in your project template.

Description Key

The Description key describes the project template. The contents of the Description key appear at the bottom of the New Project Assistant when you select the project template.

Identifier Key

The Identifier key is a string value that uniquely identifies your template. It takes the following form:

com.CompanyName.TemplateName

InjectionTargets

The InjectionTargets key is an array of strings. The strings are the identifiers of project templates. The InjectionTargets key is a new key, which didn’t exist when I originally researched custom project templates. A Google search turned up no results. You’re on your own.

Kind Key

The Kind key is a string value. It should have the following value:

Xcode.Xcode3.ProjetTemplateUnitKind

If you inherit from another template, you shouldn’t have to specify the Kind key.

MacOSXVersionMin Key

The MacOSXVersionMin key is the earliest version of Mac OS X that can use the template.

Nodes Key

The Nodes key is an array key that creates a file in the project. Add a string key for each file you want to be created in the project. The value for the key is the name of the file.

Options Key

The Options key is an array that lets you add controls to the New Project Assistant. An example of a custom control is the Type pop-up menu for command-line tool projects that lets you choose the language for the project. The Type menu is an example of a custom control.

Create a dictionary key for each control you want to add. Add keys to the dictionary key. The following are common keys for controls:

• Type identifies the type of control. Pop-up menus should use a value of popup. Checkboxes should use a value of checkbox. Text fields should use a value of text. Combo boxes should use a value of combo.
• Name is the label for the control.
• Description contains tool tip text for the control.
• Identifier is a string that uniquely identifies the control.
• Default is a string that provides a default value for a control.
• Values is an array that contains the entries for a combo box or pop-up menu.
• Required is a Boolean key that says whether a condition has to be true for the control to be enabled.

You can see an example of the Required key if you create a Cocoa application. The Document Extension text field is disabled unless you select the Create Document-Based Application checkbox. If you use the Required key, you must add a RequiredOptions dictionary key that contains the conditions.

Platforms Key

The Platforms key is an array of strings that identifies the platforms the template works on. A Mac project template has the following value:

com.apple.platform.macosx

An iOS project template has the following value:

com.apple.platform.iphoneos

Project Key

The Project key is a dictionary key that contains build settings. For those of you creating project templates for personal use, I recommend using a configuration settings file instead of placing build setting values in the project template. A reason to add build settings is if you want to add libraries to the project template. Add a build setting for linker flags and add the flags for the libraries, such as -lLibraryName.

If you use the Project key to place build settings in the project template, you will most likely need to create additional dictionary keys inside the Project key. Create a Configuration dictionary key for configuration-specific build settings. Inside the Configurations dictionary, create Debug and Release dictionaries. Place your configuration-specific build settings inside the Debug and Release dictionaries. Create a SharedSettings dictionary for any build settings that apply to all build configurations. Place any build settings that apply to all build configurations inside the SharedSettings dictionary.

SortOrder Key

I’m not exactly sure what the SortOrder key does. I haven’t seen a sort order value other than 1 in Apple’s templates.

Target Key

The Targets key is an array key you use to add frameworks, libraries, build phases, and build settings to the template. The build settings you add to the Targets key apply to the target while the build settings you add to the Project key apply to the project.

To add frameworks to the template, add a Frameworks key to the Targets key. The Frameworks key should be an array. Add string keys to the Frameworks key. The value of a string key is the name of the framework. None of Apple’s project templates use a library so I don’t know what you have to do to add a library to the Target key.

To add build phases, create a dictionary key named BuildPhases. Add a dictionary key for each build phase you want in the project template. At a minimum you need to add a Class string key to the dictionary key that contains the name of the build phase. Use the following values:

• Sources is the name for the Compile Sources build phase.
• Frameworks is the name for the Link Binary with Libraries build phase.
• Resources is the name for the Copy Bundle Resources build phase.
• CopyFiles is the name for the Copy Files build phase.
• ShellScript is the name for the Run Script build phase.
• Headers is the name for the Copy Headers build phase.
• Rez is the name for the Build Carbon Resources build phase.

It doesn’t matter what you choose from the Test Type menu. You’ll probably delete the unit test Xcode creates and add your tests. You can add your tests to both test types.

Open Xcode’s preferences. Click the General button. Choose Uses Separate Tab from the Double Click Navigation menu.

Now when you double-click a file in the project navigator, Xcode opens the file in a new tab.